Summary

99minds Gift Cards can be created and updated from iPaaS.com Gift Card data through Manual Sync or an outbound transfer. On creation the integration issues a new 99minds Gift Card and links it to a customer; on update it reloads or redeems the card to reconcile its balance with the iPaaS.com value.

ID Format

Manual Sync ID Format

On the iPaaS.com Manual Sync page, enter the iPaaS.com Gift Card Id — for example, 10828.

External ID Format

After a successful transfer, the 99minds Gift Card card id is saved as the external-id link (for example, card_1eaa3f7f34e041791d). Subsequent updates use this link to reload or redeem the same 99minds card rather than issuing a duplicate.

Deleted Record Support

Outbound delete is not supported. This collection issues, reloads, and redeems Gift Cards only; the Delete operation is not implemented, delete mappings are not included in the default template, and removing a Gift Card in iPaaS.com does not delete it in 99minds.

Mapping Collection Status

Status: Enabled.
Trigger Events: Outbound transfers fire from the iPaaS.com Outbound Data Flows the subscriber subscribes to — giftcard/created, giftcard/updated, giftcard/deleted. Manual Sync is available at any time. Whether a transfer issues a new card or reloads/redeems an existing one is determined by whether the card is already linked by an external id.

Duplicate or Conflicting Mappings

The Add/Update 99minds Gift Card TO iPaaS.com collection moves the same Gift Cards in the opposite direction (99minds → iPaaS.com). Decide which system is the source of truth for the card balance so the two directions do not overwrite each other.

Collision Handling

This collection has collision handling enabled. The Collision Handling Method on the mapping collection is set to Update and Link. Subscribers choose the method on the mapping collection from the four iPaaS.com options:

Error: reject the duplicate.
Remap and Link: link the matched record, then re-run the transfer as an update.
Update and Link: update the matched record and link the new entry (the option configured here).
Update and No Link: update the matched record without linking.

When 99minds rejects an issuance because the card already exists ("The card is already issued or sold"), the integration finds the existing card by its number (CustomerCardNumber) through a paginated search of the 99minds Gift Cards list and supplies its 99minds card id as the match. The Update and Link method then updates that card and links it, so the transfer completes as an update — restoring the external-id link instead of creating a duplicate. The match requires CustomerCardNumber to be set and unique; if it is not set, the conflict cannot be recovered.

Supported Child Collections

None — this is a standalone collection with no dependent child collections.

System Caveats

99minds Caveats

A Gift Card cannot be issued without a Campaign Id. Configure the "Campaign Id" subscription preset (or map the field) before enabling.
When CustomerCardNumber is provided, 99minds uses it as the card number instead of generating one; it must be unique.
A Gift Card can be created with any customer email even if the customer does not already exist — 99minds auto-creates a customer (without a name) from the email. To prevent that, map CustomerEmail through the alternative formula shown in the Mappings section.

iPaaS.com Caveats

The customer must be resolvable (by CustomerId or receiving email) so the card is linked to a 99minds customer.
Gift Card records are processed when already linked (any status except Pending) or, when not yet linked, only if Active with a Balance greater than 0. A terminal status (Expired / Void / Redeemed) on a linked card still transfers and is redeemed to a 0 balance by the Amount formula; Pending is ignored (see the Mapping Filter).
Implementation item to check — Receiving Customer Email dependency. The example mappings resolve the card's customer primarily by the iPaaS.com Receiving Customer Email: when a receiving email is present the CustomerId formula returns nothing, so the email becomes the primary link to a 99minds customer. If your gift cards do not always populate a receiving customer email, adjust the CustomerId and CustomerEmail mapping logic before relying on this collection in production. This item is also listed in the Known Limitations article.

Integration-Specific Caveats

On update, if the target Amount equals the live 99minds balance, no reload or redeem call is made and the transfer is marked successful.
No status operation (activate / deactivate / void / delete). The collection issues a card and reloads or redeems its balance only — it does not call any 99minds activate, deactivate, or void operation, and delete is not implemented. A card is taken out of use by zeroing its balance: changing it to a terminal status (Expired / Void / Redeemed) makes the Amount formula send 0, redeeming the 99minds card to a zero balance on the next transfer so it can no longer be spent (setting the mapped Balance to 0 directly has the same effect). The 99minds status itself is not changed — activating, deactivating, or voiding by status must be done in the 99minds portal. The expiration date can be changed on update via 99minds extend_expiry, which only accepts a later date (an expiration earlier than the card's current one is rejected).

Expiration Date Handling

The ExpirationDate is optional. When the iPaaS.com Gift Card has an expiration date, it is sent to 99minds as an ISO 8601 date-only value (yyyy-MM-dd); when it is empty, no expiration date is sent.

On Add (issuance): the expiration date is included when the new Gift Card is issued in 99minds.
On Update (established card): when the iPaaS.com expiration date changes on a card that is already linked to a 99minds card, the integration calls 99minds extend_expiry to propagate the new date. If the expiration date is unchanged, no expiry call is made.
Extend only — the expiration date cannot be reduced. 99minds only supports extending a card's expiration to a later date. An expiration earlier than the card's current expiration in 99minds is rejected with "Expiration date cannot be less than the current one" and the transfer fails. To take a card out of use before its expiration, set the card's status to Void or Expired in iPaaS.com instead — the integration redeems the card to a zero balance so it can no longer be spent (see Integration-Specific Caveats).

Setup Requirements

iPaaS.com Configuration

Subscribe to the Gift Card outbound triggers under Outbound Data Flows: giftcard/created, giftcard/updated, giftcard/deleted.
Configure the subscription presets: Campaign Id (required for issuance) and Store Ref Id or Client Store Id (99minds requires one on every write — use only one).

99minds Configuration

Campaign Id: In the 99minds portal, open Programs and the relevant campaign; the Campaign ID appears in the campaign details or the URL.
Store Ref Id: In the 99minds portal, go to Configure → Stores, open the store, and copy the store_ref value.
Client Store Id: On the same Configure → Stores page, this is the merchant-provided store identifier. Use either Store Ref Id or Client Store Id, not both.

Authentication & Security

Authentication uses the 99minds API key configured on the subscription — see the 99minds Installation Instructions.

Integration Flow

Confirm the Gift Card record passes the collection filter (Type = Gift Card; an already-linked card passes for any status except Pending, while a not-yet-linked card must be Active with a Balance greater than 0).
Resolve the 99minds customer for the card. In the example mappings, when a receiving customer email is present it is used to locate (or create) the customer; otherwise the customer is resolved from the external-id link (by iPaaS.com Customer Id), falling back to the receiving customer email.
On a new card (Add), issue a new Gift Card in 99minds with the mapped amount, card number, customer, and campaign, and save the returned card id as the external-id link.
On an existing card (Update), fetch the current 99minds balance and reload (increase) or redeem (decrease) to match the target Amount. If the amount is unchanged, no call is made.
After issuing a new card, resolve the 99minds card id by looking up the issued card by its number (the issue response does not return the id) and save it as the external-id link.
If 99minds reports the card is already issued (a collision), recover by finding the existing card by its number and retrying as an update, which restores the external-id link instead of creating a duplicate.

Mappings

Add/Update 99minds Gift Card FROM iPaaS.com

Mapping Filter

if (Type == "Gift Card") {
    var giftCardId = await GetExternalIdAsync(Id, "Gift Card", SpaceportSystemId);
    if (giftCardId != null && giftCardId != "" && Status != "Pending")
        return true;
    if (Status == "Active")
        return Balance > 0;
    return false;
}
return false;

Filter Description. Only Gift Card records are processed; other record types are excluded. For a card that is already linked to a 99minds card (an external id was saved from a prior transfer), the transfer runs for any status except Pending — Active, Expired, Void, and Redeemed all continue to sync (the Amount formula forces the balance to 0 for the non-Active statuses, so terminal cards are redeemed to zero), while Pending updates are ignored. For a card that is not yet linked, only an Active card with a Balance greater than 0 is processed, so brand-new Pending or zero-balance cards are skipped.

Description: Issues a new 99minds Gift Card (Add) or reconciles an existing card's balance via reload/redeem (Update), linking it to the resolved 99minds customer.

Mapping Type	Source Field (iPaaS.com)	Destination Field (99minds)	Description
Dynamic Formula	(see formula below)	Amount	Required (must be > 0 to issue or reload). The card value, resolved from Balance and Status: the Balance when the card is Active, otherwise 0. Drives the reload/redeem delta on update, so a terminal status (Expired / Void / Redeemed) redeems the card to a 0 balance.
Field	ReceivingCustomerEmail	CustomerEmail	Drives the customer association in the example mappings: when a receiving email is present it is used to locate (or create) the 99minds customer. Required for the example mappings — see the Receiving Customer Email caveat and the alternative formula below.
Dynamic Formula	(see formula below)	CustomerId	Resolves the 99minds Customer Id from the external-id link, falling back to the receiving email. The example formula returns nothing when a receiving email is present, so CustomerEmail effectively takes priority; CustomerId is used only when no receiving email is available.
Field	ReceivingCustomer	CustomerName	Recommended. Display name on the issued card.
Dynamic Formula	(see formula below)	ExpirationDate	Optional. Sent only when the iPaaS.com Gift Card has an expiration date, formatted as an ISO 8601 date-only value (yyyy-MM-dd); when empty, no expiration date is sent.
Field	Description	TransactionDescription	Recommended. Attached to the issuance or adjustment transaction.
Field	Number	CustomerCardNumber	Required for this flow. Assigned as the card number; the integration uses it to resolve the 99minds card id after issuance and to recover the existing card if 99minds reports it is already issued (collision handling). Must be unique.

Amount formula:

if (Status == "Active")
    return Balance;
return 0;

The amount is the card Balance only while the card is Active; for any non-Active status (Expired, Void, Redeemed, Pending) it is 0. On an already-linked card this drives a redeem down to a 0 balance when the status becomes terminal — the integration's way of taking a card out of use, since it has no activate/deactivate/void operation.

CustomerId formula:

var customerId = await GetExternalIdAsync(CustomerId, "Customer", SpaceportSystemId);
if (ReceivingCustomerEmail != null && ReceivingCustomerEmail != "")
    return null;
if (customerId == null || customerId == "")
    return await GetCustomerIdByEmail(ReceivingCustomerEmail);return customerId;

When a ReceivingCustomerEmail is present, the formula returns nothing so the CustomerEmail mapping drives the customer association by email; the linked Customer Id is used only when no receiving email is available. Because the example formula gives the receiving email priority, a ReceivingCustomerEmail value is required for the example mappings. If your gift cards do not always populate a receiving customer email, adjust this formula (and the CustomerEmail mapping) with your own logic — for example, resolving by the linked Customer Id first — so the customer can still be resolved. This implementation item is also listed in the Known Limitations article.

ExpirationDate formula:

if (ExpirationDate == null)
    return null;// ISO 8601 date-only format — e.g. 2026-06-30
return ExpirationDate.Value.ToString("yyyy-MM-dd");

Optional — prevent customer auto-creation on CustomerEmail: by default 99minds auto-creates a customer (without a name) from any email that does not match an existing customer. To avoid that, map CustomerEmail with the following formula instead, which returns the email only if a matching 99minds customer already exists (otherwise null, creating no customer):

await ValidateCustomerEmail(ReceivingCustomerEmail);

Campaign Id and Store Ref Id / Client Store Id are supplied from subscription presets (or an optional mapped field), not from the field mappings above — see Setup Requirements.

Error Handling

"The card is already issued or sold": 99minds rejects issuing a card whose number already exists. The integration recovers automatically (collision handling): it finds the existing card by its number, links the recovered card id, and retries as an update. No subscriber action is required as long as CustomerCardNumber is set and unique.
"Gift Card update failed: Could not retrieve current card state for card_id ...": the integration could not load the existing 99minds card before reloading or redeeming (for example, the linked card id no longer resolves in 99minds). Confirm the card still exists in 99minds.
"Gift Card creation failed: ...": 99minds returned an error (or no data) when issuing the card; the message from 99minds is included. Review the message and the card and customer inputs.

Testing & Validation

Test Scenarios

Issue a new card — create an iPaaS.com Gift Card (Type Gift Card, Active, Balance > 0) with a unique card number and a resolvable customer, transfer it, and confirm a new 99minds Gift Card is issued with the matching balance and linked customer.
Reload — increase the iPaaS.com Balance and re-transfer; confirm 99minds reloads to the new balance.
Redeem — decrease the iPaaS.com Balance and re-transfer; confirm 99minds redeems down to the new balance.
No-op update — re-transfer without changing Balance; confirm no reload or redeem call is made and the transfer succeeds.
Customer fallback — transfer a card with no linked CustomerId but a valid ReceivingCustomerEmail; confirm the customer is resolved (or created) and the card is linked.
Collision recovery — transfer a card whose number already exists in 99minds; confirm the integration recovers via CustomerCardNumber and completes as an update.
Filter — new card — transfer a new (unlinked) record with Balance 0 and confirm it is excluded; confirm a new Pending card is also excluded; confirm a new Active card with Balance > 0 issues.
Filter — terminal status on a linked card — on an already-linked card, change the Status to Expired, Void, or Redeemed and re-transfer; confirm it still transfers and the 99minds balance is redeemed to 0 (Amount formula). Confirm a Pending update on a linked card is ignored (no change).
Expiration change — on an already-linked card, set a later expiration and re-transfer; confirm 99minds updates the expiration via extend_expiry. An earlier date is rejected by 99minds.

Validation Checklist

New cards are issued in 99minds with the correct balance, card number, and customer link.
Reload and redeem reconcile the 99minds balance to the iPaaS.com Balance.
The external-id link (99minds card id) is saved and reused on subsequent updates.
Duplicate-issuance errors are recovered automatically when CustomerCardNumber is unique.

Additional Notes

Campaign Id is required for issuance; configure it before enabling the collection.
Store Ref Id and Client Store Id are mutually exclusive, and 99minds requires one on every write — use only one. A single store can serve all transactions, or use one store per location to track where each transaction occurs.

99minds from iPaaS.com Gift Card Mapping Documentation