Shopify to iPaaS.com Gift Card Mapping Documentation

Shopify Plus gift cards can be brought into iPaaS.com so that gift cards issued in Shopify are represented for reporting and downstream business processes. The relevant collection is Add/Update Shopify Plus Gift Card TO iPaaS.com, which supports the Add/Update sync type. The gift card record in iPaaS.com is a read-only reflection of Shopify state — iPaaS.com cannot adjust Shopify gift-card balances, and the gift card code is never exposed by Shopify.

ID Format

Gift cards are identified in iPaaS.com by the Shopify gift card id, which is written to the iPaaS.com gift card Number. The gift card Code (the value customers redeem) is private to Shopify and cannot be retrieved through the API. The Shopify gift card id is also saved as the external-id link so subsequent updates target the same iPaaS.com gift card.

Deleted Record Support

Gift cards are not deleted from iPaaS.com through this collection. A gift card that is disabled or expired in Shopify is reflected through its Status (see the status lookup translation), not by deletion.

Mapping Collection Status

Status: Disabled by default. The mapping filter 1==0 blocks all records; change it to 1==1 (or clear it) to enable on a Shopify Plus store.
Trigger: Shopify does not emit a gift-card webhook. Gift cards reach iPaaS.com as a prerequisite/post-action of order processing (when an order sells or redeems a gift card) and through bulk processing. An internal giftcards/create hook — not sent by Shopify — is registered to allow gift-card bulk processing to fire.

Duplicate or Conflicting Mappings

The opposite-direction collection Add Shopify Plus Gift Card FROM iPaaS.com creates gift cards in Shopify from iPaaS.com data (one-time, add-only). Balances cannot round-trip between the two directions because Shopify gift-card balances are immutable after creation.

Supported Child Collections

None. Add/Update Shopify Plus Gift Card TO iPaaS.com is a standalone collection with no child collections.

System Caveats

iPaaS.com Caveats

The iPaaS.com gift card represents Shopify state for reporting; it is not a source of truth for issuing or adjusting balances.
The CustomerId mapping resolves the related iPaaS.com customer from the Shopify customer id.

Shopify Caveats

Gift cards are available on all Shopify plans, but non-Plus plans support more limited gift card functionality than Shopify Plus; this collection targets the Shopify Plus gift card experience.
Gift card codes are private and never exposed via API; the iPaaS.com number is the Shopify id.
Balance adjustments cannot be pushed from iPaaS.com into Shopify.

Setup Requirements

iPaaS.com Configuration

Enable the Add/Update Shopify Plus Gift Card TO iPaaS.com mapping collection by changing its filter from 1==0 to 1==1.
Ensure the Shopify Gift Card Status To iPaaS.com lookup translation is configured.

Shopify Plus Configuration

The Shopify connection must be authorized with gift-card read access (read_gift_cards). Note that Shopify does not send a gift-card webhook; transfers are driven by order processing and bulk processing.

Integration Flow

A Shopify Plus order sells or redeems a gift card, or a bulk gift-card process runs.
The integration retrieves the gift card from Shopify.
The mapping transforms the Shopify gift card into the iPaaS.com gift card schema.
The gift card is created or updated in iPaaS.com for reporting and downstream use, linked by the Shopify gift card id.

Mappings

Add/Update Shopify Plus Gift Card TO iPaaS.com (284596)

Mapping Type	Source Field (Shopify)	Destination Field (iPaaS.com)	Requirement / Note
Field	Id	Number	Required. Derived from the Shopify gift card id, not the code.
Field	Note	Description	Recommended.
Static	Gift Card	Type	Required. Identifies the record type.
Field	Balance	Balance	Required. Read-only; cannot be changed by iPaaS.com.
Lookup Translation	Shopify Gift Card Status To iPaaS.com	Status	Recommended. Calculates expire/disable state and balance, converts to iPaaS.com status.
Dynamic Formula	`GetSpaceportId(CustomerId, "customer", SpaceportSystemId)`	CustomerId	Recommended. Resolves the iPaaS.com customer id from the Shopify customer id.
Dynamic Formula	`SpaceportSystemId`	Originating_SystemId	Recommended. Originating iPaaS.com system id.
Field	ExpiresOn	ExpirationDate	Optional.
Field	InitialValue	OriginalAmount	Optional.

Lookup Translation — Shopify Gift Card Status To iPaaS.com

Source condition (Shopify)	Destination value (iPaaS.com)
`CoalesceToDateTime(DateOnly(DisabledAt), MaximumDateTime()) < CurrentDateTime()`	Void
`CoalesceToDateTime(DateOnly(ExpiresOn), MaximumDateTime()) < CurrentDateTime()`	Expired
`Balance <= 0`	Active
`true`	Active

Error Handling

Invalid expiration date: the transfer fails if the date is invalid.
Missing balance: Balance is required and cannot be null.

Testing & Validation

Gift card sync: a Shopify gift card appears in iPaaS.com with the correct balance and metadata.
Status mapping: status values translate correctly via the lookup translation.
Customer linkage: the gift card associates with the correct iPaaS.com customer.
Validation checklist: gift card visible in iPaaS.com; balance matches Shopify; status translation correct; expiration and original amount captured.

Additional Notes

Gift card issuance and balance adjustments happen in Shopify, not iPaaS.com (this collection reads gift cards into iPaaS.com for reporting only). Shopify Plus offers the fullest gift card functionality; other plans are more limited.
Because Shopify sends no gift-card webhook, do not expect gift cards to flow in real time on creation; they arrive through order processing and bulk runs.