Overview
When a Gift Certificate is created or updated in NetSuite and its remaining balance is greater than zero, it is transferred to iPaaS.com as a Gift Card record. This mapping collection handles both manual synchronization and polling-based automatic synchronization using the NetSuite Gift Certificate API.
Gift Certificates are generated in NetSuite only after a Sales Order is billed. If the order has not been invoiced, the Gift Certificate record will not exist and will not be available for synchronization.
Before You Begin
Ensure the following prerequisites are in place before configuring this integration.
NetSuite Requirements
NetSuite must have the Gift Certificate item type enabled so that gift certificates can be created and managed when sales orders are billed.
Gift Certificates are created only after the Sales Order is billed. If the order is not invoiced, the gift certificate record will not exist and will not be available for synchronization.
The Gift Certificate must have an AmountRemaining greater than zero to pass the mapping filter.
Email and customer information may be optional in NetSuite; if these fields are empty, the corresponding receiving customer details in iPaaS.com may also remain blank.
iPaaS.com Requirements
Access to iPaaS.com with permissions to create and update Gift Card records.
Gift Card Number must be unique in iPaaS.com. Duplicate numbers will cause creation failures or require update handling.
Required fields must be present during creation: Number, Type, Status, and Balance.
Status values must match supported iPaaS.com statuses (Active, Redeemed).
ID Format
When manually transferring a Gift Certificate from NetSuite, enter the NetSuite Gift Certificate internal ID (e.g., 10) into the input field on the iPaaS.com manual sync page.
Mapping Collection Status
Status: Conditional
Trigger Events: Create and Update
Data Requirements
The following fields are required for successful Gift Card creation in iPaaS.com.
Mandatory Fields
Number (GiftCertCode)
Type (static: "Gift Card")
Status (derived from AmountRemaining)
Balance (AmountRemaining)
Originating_SystemId (SpaceportSystemId)
Recommended Fields
Description (Message)
PurchaseDate (CreatedDate)
ReceivingCustomer (Name)
ReceivingCustomerEmail (Email)
ExpirationDate
OriginalAmount
System Caveats
NetSuite Caveats
Gift Certificate Availability: Gift Certificates are created only after the Sales Order is billed in NetSuite. If the order is not invoiced, the Gift Certificate record will not exist and will not be available for synchronization.
Optional Customer Fields: Email and customer name fields may be empty in NetSuite. If these fields are not populated, the corresponding receiving customer details in iPaaS will also remain blank.
iPaaS.com Caveats
Unique Gift Card Number: The Gift Card Number must be unique in iPaaS.com. If a Gift Card with the same number already exists, the record may fail to create or may require update handling.
Required Fields: Number, Type, Status, and Balance must be present during creation. Missing values in the source data will cause the synchronization to fail.
Status Values: Status values must match supported iPaaS statuses (Active, Redeemed). Unsupported values returned by formulas or mappings will cause validation errors.
Authentication and Security
NetSuite uses OAuth 2.0 authentication to securely connect with iPaaS.com. This method allows the integration to access NetSuite APIs without exposing user credentials. OAuth 2.0 must be configured in NetSuite by creating an Integration Record, enabling Token-Based Authentication / OAuth 2.0, and granting the required permissions to the integration role. The generated Client ID and Client Secret are used by iPaaS.com to obtain an access token and securely authenticate API requests to NetSuite.
Integration Flow
The integration processes NetSuite Gift Certificate records as follows:
A Gift Certificate is created or updated in NetSuite after a Sales Order is billed.
The mapping filter evaluates whether AmountRemaining is greater than zero.
Gift Certificates that do not meet the filter criteria (fully redeemed) are skipped.
iPaaS.com authenticates with NetSuite using configured OAuth 2.0 credentials.
Gift Card fields are populated using mapped NetSuite data, including the dynamically determined Status.
The Gift Card record is created or updated in iPaaS.com.
Transfer status and any errors are logged in iPaaS.com.
Mappings
Parent: NetSuite Add Gift Certificate to iPaaS.com
Purpose and Function
This mapping collection transfers NetSuite Gift Certificate records to iPaaS.com as Gift Card records. It maps identification, status determination, financial amounts, customer details, and lifecycle dates. Only Gift Certificates with a remaining balance greater than zero are processed.
Mapping Filter
AmountRemaining > 0
Description
This filter ensures that only Gift Certificates with a remaining balance greater than zero are processed. Fully redeemed Gift Certificates (AmountRemaining ≤ 0) are excluded to avoid creating unnecessary records in iPaaS.com.
Mapping Type | Source (NetSuite) | Destination (iPaaS.com) | Description |
Field | GiftCertCode | Number | (Required) Maps the unique Gift Certificate code as the Gift Card number used to identify the record. |
Field | Message | Description | (Recommended) Maps the message associated with the Gift Certificate for reference or display purposes. |
Static | Gift Card | Type | (Required) Sets the record type to "Gift Card" to ensure the record is correctly categorized in iPaaS.com. |
Field | AmountRemaining | Balance | (Required) Maps the remaining unused balance of the Gift Certificate. |
Dynamic Formula |
| Status | (Required) Determines the Gift Card status based on the remaining balance. Returns "Active" if balance is greater than zero; returns "Redeemed" otherwise. |
Field | CreatedDate | PurchaseDate | (Recommended) Maps the Gift Certificate creation date as the purchase date. |
Field | Name | ReceivingCustomer | (Recommended) Maps the name of the customer receiving the Gift Certificate. |
Field | ReceivingCustomerEmail | (Recommended) Maps the recipient's email address. | |
Field | SpaceportSystemId | Originating_SystemId | (Required) Maps the system identifier to track the originating system of the Gift Certificate record. |
Field | ExpirationDate | ExpirationDate | (Recommended) Maps the Gift Certificate expiration date. |
Field | OriginalAmount | OriginalAmount | (Recommended) Maps the original issued value for reference and financial tracking. |
Error Handling
Required Field Missing
Record creation fails with a validation error.
Description: iPaaS.com requires mandatory fields (Number, Type, Status, Balance) to create a Gift Card record. If NetSuite does not provide values for required fields during synchronization, the record creation fails.
Resolution: Ensure the following NetSuite fields are populated: GiftCertCode, AmountRemaining. Verify that the static Type mapping ("Gift Card") and dynamic Status formula are configured correctly.
Invalid Status Value
Validation error on Status field.
Description: The status returned by the dynamic formula does not match a supported iPaaS.com value.
Resolution: Ensure the dynamic formula only returns supported status values: "Active" or "Redeemed."
Gift Certificate Not Found
Record not found during manual sync.
Description: During manual synchronization, the entered Gift Certificate ID does not exist in NetSuite.
Resolution: Verify the correct NetSuite Gift Certificate internal ID before initiating manual synchronization.
Duplicate Gift Card Number
Gift Card creation fails due to duplicate Number.
Description: A Gift Card with the same Number (GiftCertCode) already exists in iPaaS.com.
Resolution: Verify whether the existing record should be updated rather than created. If a duplicate is expected (e.g., from a re-sync), ensure the mapping collection handles updates.
Validation and Testing
Validation Rules
Gift Certificate Balance Validation: Only Gift Certificates with AmountRemaining greater than zero are eligible for synchronization. This rule prevents fully redeemed certificates from being transferred.
Required Field Validation: The following fields must be present before creating a record in iPaaS.com: Number, Type, Status, and Balance.
Status Determination Rule: Gift Card status is determined dynamically using the remaining balance: Balance > 0 returns "Active"; Balance ≤ 0 returns "Redeemed."
Validation Checklist
Gift Certificate record exists in NetSuite and has been billed.
GiftCertCode is unique and properly mapped to Number.
AmountRemaining is greater than zero for new Gift Card creation.
Required fields (Number, Type, Status, Balance) are populated after mapping.
Status formula returns a valid value (Active or Redeemed).
Customer email and name fields are mapped correctly if available in NetSuite.
SpaceportSystemId is populated for originating system tracking.
ExpirationDate and OriginalAmount are mapped if lifecycle tracking is needed.
Test Scenarios
Scenario 1: Create Gift Certificate with Positive Balance
Create a new Gift Certificate in NetSuite with a remaining balance greater than zero. Execute sync. Verify the Gift Card is created in iPaaS.com with status "Active" and the correct balance value.
Scenario 2: Gift Certificate Fully Redeemed
Update a Gift Certificate in NetSuite so that AmountRemaining equals zero. Execute sync. Verify the Gift Card is updated in iPaaS.com with status "Redeemed."
Scenario 3: Manual Sync Using Gift Certificate ID
Manually trigger synchronization using the Gift Certificate internal ID on the iPaaS.com manual sync page. Verify the corresponding Gift Card record is retrieved from NetSuite and created in iPaaS.com.
Scenario 4: Missing Required Field (Failure Case)
Attempt synchronization when a required field (e.g., GiftCertCode or AmountRemaining) is missing. Verify the system rejects the record and logs a validation error.
Scenario 5: Duplicate Gift Card Number (Failure Case)
Sync a Gift Certificate whose GiftCertCode already exists as a Gift Card Number in iPaaS.com. Verify the system handles the duplicate appropriately (update or error, depending on configuration).
Additional Notes
Gift Certificates are generated only after billing a Sales Order in NetSuite, so synchronization depends on the billing process being complete.
The mapping filter prevents fully redeemed Gift Certificates from being created in iPaaS.com to avoid unnecessary records.
Manual synchronization can be used to transfer historical or missed Gift Certificate records.
The Originating_SystemId field tracks the source system, ensuring the record is recognized as originating from NetSuite.
ExpirationDate and OriginalAmount fields are optional but recommended for accurate financial and lifecycle tracking.
Email and customer name fields are optional in NetSuite. If not populated at the source, the corresponding iPaaS.com fields will remain blank.