Summary
Gift cards are transferred from Adobe Commerce/Magento 2 into iPaaS.com as Gift Card records. Each Magento gift card becomes one iPaaS.com Gift Card, carrying the gift card code as the card number, the card's balance, the recipient's name and email address, and a fixed type and status that identify the record as an active gift card.
The collection is add-only. It creates gift cards that do not yet exist in iPaaS.com and does not overwrite cards that are already there, so it is intended to run when a card is first issued in Magento rather than as an ongoing balance-synchronisation mechanism.
This collection is a prerequisite for the gift-card payment paths. Orders, deposit tickets and gift card tickets all resolve a redeemed card by its number, so a card must have reached iPaaS.com through this collection before any of those can link to it.
ID Format
Manual Sync ID Format
Enter the Adobe Commerce/Magento 2 gift card code — the card number itself, for example 6X9K2QW4TM10.
The card is identified by its code rather than by an internal record identifier.
External ID Format
After a successful transfer, iPaaS.com stores the Adobe Commerce/Magento 2 gift card code as the external ID on a record linking the Magento gift card to the iPaaS.com Gift Card. That record is what the gift-card payment and gift-card line mappings on the order and ticket families read when they resolve a redeemed card to its iPaaS.com identifier.
Deleted Record Support
Outbound delete is not supported for gift cards. Removing a gift card in Adobe Commerce/Magento 2 does not remove the corresponding iPaaS.com Gift Card, and delete mappings are not included in the default templates for this collection.
Custom Field Support
This collection reads no custom fields. Every value it writes comes from a standard field on the Magento gift card, a fixed value, or the transfer date.
Mapping Collection Status
Status: Enabled. This collection ships enabled and processes every Adobe Commerce/Magento 2 gift card it receives.
Trigger Events: Creation of a gift card in Adobe Commerce/Magento 2, plus Manual Sync on demand. Gift cards sold on an order are also transferred automatically as a prerequisite of that order's transfer.
Adobe Commerce/Magento 2 has no native webhook capability, so event-driven transfers depend on the third-party webhook extension being installed and configured in the Magento store. Manual Sync is always available regardless.
Duplicate or Conflicting Mappings
No other collection creates iPaaS.com Gift Card records from Adobe Commerce/Magento 2, so there is no competing collection to reconcile filters with. There is, however, an ordering dependency:
The gift card ticket family — Add/Update Adobe Commerce/Magento 2 Gift Card Ticket TO iPaaS.com and its children, including Add/Update Adobe Commerce/Magento 2 Gift Card Ticket Payment Gift Card TO iPaaS.com — resolves gift cards by their number.
The gift-card payment children on the other ticket families — Add/Update Adobe Commerce/Magento 2 Order Payment Gift Card TO iPaaS.com and Add Adobe Commerce/Magento 2 Deposit Ticket Payment Gift Card TO iPaaS.com — resolve gift cards by their number as well.
The gift-card line children — Add/Update Adobe Commerce/Magento 2 Order Line Gift Card TO iPaaS.com and Add/Update Adobe Commerce/Magento 2 Gift Card Ticket Line TO iPaaS.com — do the same.
Because all of those lookups match on the gift card number, a card must have reached iPaaS.com through this collection before they can succeed. A payment made with a card that was never transferred has no Gift Card record to link to. Subscribers or their MiSP enabling the ticket and payment families should confirm this collection is enabled and that the store's existing cards have been loaded first.
Duplicate matching
This integration implements no selectable collision-handling methods, and the behavior is not configurable on this collection. Because the collection is add-only, a card already present in iPaaS.com is not overwritten — the transfer creates cards that do not yet exist and leaves existing ones as they are.
Unmapped field overwrite risk
The add-only setting means this collection does not overwrite an existing iPaaS.com Gift Card, so the usual re-transfer overwrite risk does not apply here. The fields it writes on creation are Number, Type, Balance, Status, PurchaseDate, ReceivingCustomer, ReceivingCustomerEmail, Originating_SystemId and OriginalAmount.
The practical consequence runs the other way: because later changes are not sent, a balance or status maintained in Magento after the card first transfers will diverge from the iPaaS.com record. Card balances after issue are maintained in iPaaS.com, or through the gift card activity workflow.
The mitigation is a DestinationValue. Where an iPaaS.com field must hold a specific value that the source card does not supply, set a DestinationValue on that mapping so the integration writes the value chosen there instead of taking it from the source.
Supported Child Collections
None. This is a standalone collection with no parent and no children. It writes a single Gift Card record and has no subordinate data to contribute.
System Caveats
Adobe Commerce/Magento 2 Caveats
Gift card capability is supplied by an extension. Gift cards are not part of a stock Magento Open Source installation, and the fields available on a card depend on the gift card extension the store runs.
Card codes must be unique. The code is the value iPaaS.com matches on, so duplicate codes in Magento cannot be distinguished once transferred.
Gift card retrieval is subject to Magento's API limits. A large initial load of existing cards can encounter Adobe Commerce/Magento 2 request-array and page-size limits. Stagger large manual catch-up runs rather than issuing them concurrently.
iPaaS.com Caveats
A system identifier is required on every Gift Card record. It must resolve to a value greater than zero, which the shipped mapping satisfies. Removing that mapping prevents the card from being written.
The card number is the match key for every downstream lookup. Remapping it would break the resolution used by the order, deposit ticket and gift card ticket payment paths.
Cards must exist before the transfers that redeem them. A gift-card payment or gift-card line naming a card that iPaaS.com does not hold cannot be linked, and the transfer of that line or payment fails.
Integration-Specific Caveats
Status is a fixed value. Every card arrives marked Active regardless of its state in Magento. A card that is already deactivated, fully redeemed, or expired when it transfers still arrives Active, and because the collection is add-only, later status changes are not sent either.
Balance and OriginalAmount come from the same source value. For a newly issued card the two are correctly identical. For a card partially redeemed in Magento before its first transfer, the remaining balance is what is recorded as the card's original amount.
PurchaseDate is the transfer date, not the purchase date. For cards that transfer as soon as they are created the two are effectively the same; for a backfill of older cards they are not.
The Type value differs from the platform's own enumeration but is accepted. The shipped fixed value is normalized on arrival and works in production. No action is required.
Setup Requirements
Adobe Commerce/Magento 2 Configuration
Confirm the gift card extension is installed and that card codes, balances and recipient details are populated.
Install and configure the third-party webhook extension if gift cards should transfer automatically as they are issued.
iPaaS.com Configuration
Enable this collection before enabling the order, deposit ticket and gift card ticket families, so redeemed cards can be resolved.
Load the store's existing gift cards before the first ticket transfers run.
Review the backfill caveats above if older, partially redeemed cards are being loaded, since the original amount and purchase date will not be exact for those.
Enable the inbound flow for Adobe Commerce/Magento 2 gift cards on the subscription's Inbound Data Flows page.
Full step-by-step setup instructions are in the Adobe Commerce/Magento 2 Installation Instructions article, and the webhook extension setup is covered in Configure Mageplaza Webhooks for iPaaS.com.
Integration Flow
A gift card is issued in Adobe Commerce/Magento 2, or an existing card is picked up by a Manual Sync.
The card is evaluated by this collection. It carries no filter, so every card received is processed.
The card payload is built: the code becomes the card number, the balance populates both the current balance and the original amount, the recipient details are carried across, and the type, status and system identifier are supplied.
The Gift Card is created in iPaaS.com, and iPaaS.com records the link between the Magento card and the new record. A card already present is not overwritten.
Later, when an order or ticket redeems that card, the gift-card payment and line mappings resolve it by its number through the link created here.
Mappings
Add Adobe Commerce/Magento 2 Gift Card TO iPaaS.com
iPaaS.com data type: Gift Card
This collection carries no mapping filter — every gift card record received is processed.
Mapping Type | Source Field (Adobe Commerce/Magento 2) | Destination Field (iPaaS.com) | Description |
Field | GiftCode | Number | Required. The gift card code. This is the value every downstream gift-card lookup matches on, so it should not be remapped. |
Static |
| Type | Required. Fixed for every card transferred. The value differs from the platform's own enumeration but is normalized on arrival and works in production. |
Static |
| Status | Required. Fixed for every card transferred. A card already deactivated, redeemed or expired in Magento still arrives marked Active. |
Dynamic Formula |
| Originating_SystemId | Required. Resolves the current subscription's system identifier, which iPaaS.com requires on every Gift Card record and which must be greater than zero. Do not change or remove this mapping. |
Field | Balance | Balance | Optional. The card's current balance at the time of transfer. |
Field | Balance | OriginalAmount | Optional. Records the value the card was issued for. Populated from the same source balance, so for a card already partially redeemed before its first transfer this records the remaining balance rather than the issued value. |
Dynamic Formula |
| PurchaseDate | Optional. Stamps the date the transfer ran, with the time portion removed. This is not the date the card was purchased in Magento. |
Field | RecipientName | ReceivingCustomer | Optional. The gift card recipient's name. |
Field | RecipientEmail | ReceivingCustomerEmail | Optional. The gift card recipient's email address. |
Error Handling
The full catalog of messages this integration produces, with causes and resolutions, is in the Adobe Commerce/Magento 2 Error Messages article. The conditions most often seen around this transfer are:
Error message: No Giftcard assigned to line item marked as gift card. An order line is marked as a gift card in Magento but the card record carries no code, so there is nothing for this collection to transfer. Resolution: confirm the gift card was issued correctly in Magento for that line, then re-sync the order.
A gift-card payment or line that cannot be linked. The card named on the payment or line does not exist in iPaaS.com. Resolution: transfer the card through this collection, then re-sync the order or ticket.
A card that does not update. Expected behavior — the collection is add-only and does not overwrite an existing record.
Errors are reported under Dashboard / Integration Monitoring / Error Logs.
Testing & Validation
Test Scenarios
Issue a gift card in Adobe Commerce/Magento 2 and confirm an iPaaS.com Gift Card is created with the correct number, balance, recipient name and email.
Manually sync using the gift card code and confirm it resolves.
Confirm the card arrives with a type of Gift Card and a status of Active.
Change the balance in Magento, re-run the transfer, and confirm the iPaaS.com record is not updated — verifying the add-only behavior.
Transfer a card that is already deactivated in Magento and confirm it still arrives marked Active.
Transfer a partially redeemed card and confirm the original amount reflects the remaining balance rather than the issued value.
Place an order paid with a card that has transferred, and confirm the gift-card payment resolves and links to the correct Gift Card.
Place an order paid with a card that has not transferred, and confirm the payment fails to link, then re-run after transferring the card.
Confirm a gift card sold on an order is transferred automatically as a prerequisite of that order.
Validation Checklist
The gift card extension in Magento populates codes, balances and recipient details.
This collection is enabled before the order, deposit ticket and gift card ticket families.
The store's existing gift cards have been loaded before the first ticket transfers run.
Card codes are unique in Magento.
The consequences of the fixed status and the shared balance source are understood for any backfill of older cards.
Additional Notes
This collection is add-only by design. Ongoing balance maintenance is not part of it; balances after issue are maintained in iPaaS.com or through the gift card activity workflow.
Three of the fixed and derived values — the status, the original amount, and the purchase date — are exact only for cards that transfer at the moment they are issued. Review them after any backfill of older cards.
The card number is the single match key that ties gift cards to the payments and lines that redeem them across three other families. Treat it as immutable.
Validate dynamic formulas in a staging environment before enabling automatic transfers in production.