Contents
Summary
Stripe customers can be kept up to date from iPaaS.com customers through outbound customer events and Manual Sync: the name, email, company, phone, description, the billing and shipping addresses, and any of Stripe's other customer settings you choose to map (see Other Stripe Fields You Can Map). The integration finds the Stripe customer linked to the iPaaS.com customer, or the one carrying its iPaaS.com id, or the one with its email, and creates one only when there is none, which the default filter does only for a linked customer whose Stripe customer was deleted. By default only customers already linked to Stripe are sent; the filter can be set to linked customers only or every customer with an email (see Mappings). Customers are also found or created automatically when an invoice is issued (see iPaaS.com to Stripe Invoice Mapping Documentation), so this collection is optional for billing.
ID Format
Manual Sync ID Format
Enter the iPaaS.com customer id on the iPaaS.com Manual Sync page, for example 166448.
External ID Format
iPaaS.com saves the Stripe customer id (it starts cus_, for example cus_VeA0XhxuSFno8y) as the external ID on its own external-ID record. The Stripe customer also carries the iPaaS.com customer id in its metadata, so it is found again even after its email changes in Stripe.
Deleted Record Support
Not supported. Customers are never deleted in Stripe from iPaaS.com: a deleted Stripe customer loses its invoices and payment history. Don't add a Delete collection for customers: a customer delete sent to Stripe is refused with STRP-BIZL-1008, and the Stripe customer is kept. A Stripe customer that was deleted in Stripe is found again by email or created again on the next send.
Custom Field Support
You can send your own values to Stripe as customer metadata. Create a custom field on the Stripe subscription's Customer table, named the way the metadata key should read in Stripe (for example loyalty_tier), and map it in this collection, for example with a Dynamic Formula such as return Comment;. The value is written to the Stripe customer's metadata under the custom field's name. When the value is blank after it was sent, the key is removed from the Stripe customer. Names that start with ipaas_ are never written from a custom field.
The Stripe customer's metadata names that start with ipaas_ belong to the integration: the iPaaS.com customer id (to find the customer again), the billing address's phone when it differs from the customer's own phone (see Stripe Caveats), and a marker that records what was last sent, so the integration knows which fields changed.
Mapping Collection Status
Status: Enabled.
Trigger Events: subscribe to customer/created and customer/updated under the subscription's Outbound Data Flows. No customer transfers automatically until you subscribe. Manual Sync is available by iPaaS.com customer id. The address child collection transfers with the customer.
Duplicate or Conflicting Mappings
Add/Update Stripe Customer TO iPaaS.com writes the same customers the other way. Decide which system owns each field before turning both on.
Customer Matching
The collection has no Collision Handling Method: the integration matches automatically, in this order.
The link: the Stripe customer linked to this iPaaS.com customer.
The iPaaS.com id: else the Stripe customer carrying its iPaaS.com customer id.
The email: else the Stripe customer with its email.
A new customer: otherwise a new Stripe customer is created.
Refusal: when two or more Stripe customers have the email and none is linked to this iPaaS.com customer, nothing is sent and the transfer is refused with STRP-BIZL-1012. Delete or re-email the extra Stripe customers in the Stripe Dashboard, then retry.
Supported Child Collections
Add/Update Stripe Customer Address FROM iPaaS.com (Customer Address): the primary billing address becomes the Stripe customer's address, and the primary shipping address its shipping address.
System Caveats
Stripe Caveats
Two addresses: Stripe keeps one billing address and one shipping address per customer; other addresses aren't sent.
Name and phone on the billing address: Stripe keeps a name and phone on the shipping address only. The billing address's name is sent as the customer's individual name, unless IndividualName is mapped. The billing address's phone is sent as the customer's phone when the customer's own Phone is blank; when the customer has a different phone of its own, the billing phone is kept in the Stripe customer's metadata. Either way it comes back unchanged TO iPaaS.com.
Country: Stripe accepts only a two-letter country code (ISO 3166-1, for example US, CA or GB). Any case is accepted and sent in capitals. A country in any other form, such as USA or United States, is refused with STRP-VALD-1012, naming the value and whether it is on the billing or shipping address, and nothing is sent to Stripe. Store two-letter codes, or add a translation on the address Country mapping that turns country names into codes.
Description length: the description is sent in full. Stripe allows up to 5,000 characters and refuses a longer one (STRP-EXTN-1004).
Rate limiting: when Stripe asks the integration to slow down, the transfer is rescheduled automatically. No action is needed.
iPaaS.com Caveats
Changed fields only: only the fields that changed in iPaaS.com since the last send are sent, so an edit made in Stripe stays until the same field changes in iPaaS.com.
Cleared values: a value blanked in iPaaS.com is cleared in Stripe on the next update, but only for a field the integration sent before. A field that was always blank in iPaaS.com, or any field of a Stripe customer the integration has never written, clears nothing, so a value typed in Stripe stays. This covers the phone, description, company, individual name, each address line, the whole shipping address, preferred languages, invoice settings, the tax IP address. A blanked TaxExempt goes back to none, a blanked CashBalance_Settings_ReconciliationMode to merchant_default, and a blanked invoice amount display or invoice template to Stripe's default. Balance, InvoicePrefix, NextInvoiceSequence, Tax_ValidateLocation and the payment fields (PaymentMethod, Source, DefaultSource, DefaultCard, DefaultBankAccount, DefaultAlipayAccount) are never cleared: a blank sends nothing.
Child collections move with the customer: don't add the address collection as a collection of its own. A record sent on its own is refused.
Setup Requirements
Stripe Configuration
Secret Key: a Stripe secret key or restricted key with the permissions listed in Stripe Installation Instructions.
iPaaS.com Configuration
Outbound Data Flows: subscribe to customer/created and customer/updated.
Custom field: Stripe Customer ID on iPaaS.com customers, written by Add/Update Stripe Customer TO iPaaS.com.
Filter: choose linked customers only (the default) or every customer with an email, as described under Mappings, before the first transfer.
Delete mapping: don't add one; customers aren't deleted in Stripe.
Integration Flow
A customer event or a Manual Sync sends an iPaaS.com customer. It passes the collection's filter when it is already linked to Stripe (or, with the every-customer filter, when it has an email).
The customer is checked before anything reaches Stripe: a blank email or one without an @ is refused (STRP-VALD-1004); an address country that isn't a two-letter code, a Balance or NextInvoiceSequence that isn't a whole number, or a TaxIdData entry that isn't type:value is refused (STRP-VALD-1012).
The Stripe customer is found (see Customer Matching) or created. Nothing has to be transferred first.
The customer's name (first and last name joined, or the company when there is neither), email, company, phone, description, iPaaS.com id, its primary billing and shipping addresses and any other fields you mapped are sent to Stripe. On an update, only the fields that changed in iPaaS.com since the last send are sent, and values blanked since then are cleared (see iPaaS.com Caveats).
iPaaS.com saves the Stripe customer id as the external ID. When Add/Update Stripe Customer TO iPaaS.com is also on, the change Stripe reports for this write isn't brought back TO iPaaS.com.
Mappings
Add/Update Stripe Customer FROM iPaaS.com
iPaaS.com data type: Customer
Mapping Filter
// Customers already linked to Stripe (kept in step). To send every customer with an email to Stripe, replace this with:
// return !string.IsNullOrEmpty(EmailAddress);
return ("" + GetCustomFieldValue(CustomFields, "Stripe Customer ID")).Length > 0;
Filter Description: by default only customers already linked to Stripe are sent: their Stripe Customer ID custom field has a value, written when Add/Update Stripe Customer TO iPaaS.com brings in or links the customer. A customer without one is skipped with no error.
Choosing which customers are sent: the filter's default rule sends linked customers only. Choose which customers this collection sends:
Linked customers only (the default): keeps customers that came from Stripe, or were linked to it, up to date. Keep the last line:
return ("" + GetCustomFieldValue(CustomFields, "Stripe Customer ID")).Length > 0;Every customer with an email: also creates a Stripe customer for each iPaaS.com customer that has none. Replace the last line with:
return !string.IsNullOrEmpty(EmailAddress);
Description: creates or updates the Stripe customer for each iPaaS.com customer.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Stripe) | Description |
Field | Company | Company | Optional. Stripe's business name, up to 150 characters, and the Stripe customer's name when the customer has no first or last name. A company blanked in iPaaS.com after it was sent is cleared in Stripe. |
Field | Comment | Description | Optional. A note on the Stripe customer, sent in full (Stripe allows up to 5,000 characters). A comment blanked in iPaaS.com after it was sent is cleared in Stripe. |
Field | EmailAddress | Required. Stripe customers are matched by email. A blank email, or one without an @, is refused. | |
Field | FirstName | FirstName | Recommended. Joined with the last name as the Stripe customer's name. |
Field | Id | IpaasCustomerId | Recommended. The iPaaS.com customer id, kept on the Stripe customer so it is found again even after its email changes in Stripe. |
Field | LastName | LastName | Recommended. Joined with the first name as the Stripe customer's name. |
Other Stripe Fields You Can Map
The template doesn't map these, but you can add any of them to Add/Update Stripe Customer FROM iPaaS.com. A field left unmapped sends nothing; a value blanked after it was sent is handled as described under iPaaS.com Caveats. Values must be in the form Stripe accepts; Stripe refuses anything else (STRP-EXTN-1004).
Destination Field (Stripe) | Description |
Name | The Stripe customer's name, up to 256 characters. When blank, the first and last name joined are used, else the company, else the email. |
IndividualName | The person's name on the Stripe customer, up to 150 characters. When blank, the billing address's name is sent instead. |
Phone | The customer's phone, up to 20 characters. When blank, the billing address's phone is sent instead. |
Balance | The customer's Stripe balance in the currency's smallest unit (cents for USD: 1250 is 12.50). A negative balance is a credit taken off the next invoice. Must be a whole number. A blank never changes Stripe's balance. |
TaxExempt | none, exempt or reverse. |
InvoicePrefix | The prefix of this customer's Stripe invoice numbers: 1 to 12 capital letters or numbers. |
NextInvoiceSequence | The number Stripe gives this customer's next invoice. A whole number. |
PreferredLocales | The customer's preferred languages for Stripe's emails and pages, most preferred first, separated by commas, for example "en, fr-CA". |
TaxIdData | The customer's tax IDs as type:value pairs separated by semicolons, for example "eu_vat:DE123456789; us_ein:12-3456789". Sent only when the Stripe customer is created. |
PaymentMethod | The id of a Stripe payment method (it starts pm_) to attach. Sent only when the Stripe customer is created. |
Source | A Stripe token or source id (it starts tok_ or src_) to add as the customer's default payment source. |
DefaultSource | The id of a payment source already on the customer (it starts card_, ba_ or src_). Sent only when an existing Stripe customer is updated. |
DefaultCard, DefaultBankAccount, DefaultAlipayAccount | Stripe's older way to set the default source: the id of a card, bank account or Alipay account already on the customer. Sent only when an existing Stripe customer is updated. |
TestClock | A Stripe test clock (it starts clock_), in Stripe test mode only. Sent only when the Stripe customer is created. |
InvoiceSettings_Footer | The default footer on this customer's Stripe invoices, up to 5,000 characters. |
InvoiceSettings_DefaultPaymentMethod | The payment method (it starts pm_) Stripe charges by default for this customer's invoices; it must already be attached to the customer. |
InvoiceSettings_RenderingOptions_AmountTaxDisplay | How the customer's invoice PDFs show amounts: exclude_tax or include_inclusive_tax. |
InvoiceSettings_RenderingOptions_Template | The id of a Stripe invoice template (it starts inrtem_) for this customer's invoices. |
Tax_IpAddress | A recent IP address of the customer, which Stripe Tax uses to tell where the customer is. |
Tax_ValidateLocation | When Stripe Tax checks the customer's location: deferred or immediately (on an update also auto). With immediately, Stripe refuses a customer whose address it can't place. |
CashBalance_Settings_ReconciliationMode | How money the customer sends by bank transfer is applied: automatic, manual or merchant_default (your Stripe account's setting). |
Add/Update Stripe Customer Address FROM iPaaS.com
iPaaS.com data type: Customer Address
Description: sends the customer's primary billing address as the Stripe customer's address (the first address when none is marked), and its primary shipping address as the shipping address, with a name and phone.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Stripe) | Description |
Field | City | City | Recommended. City. |
Field | Country | Country | Recommended. A two-letter country code (for example US, in any case). Any other form is refused with STRP-VALD-1012 and nothing is sent. |
Field | IsPrimaryBilling | IsPrimaryBilling | Recommended. The address marked primary billing becomes the Stripe customer's address; when none is marked, the first one is used. |
Field | IsPrimaryShipping | IsPrimaryShipping | Recommended. The address marked primary shipping becomes the Stripe customer's shipping address. |
Field | Address1 | Line1 | Recommended. Street address, line 1. |
Field | Address2 | Line2 | Optional. Street address, line 2. |
Dynamic Formula |
| Name | Optional. The address's first and last name joined. On the shipping address it is the shipping name; on the billing address it is sent as the customer's individual name (up to 150 characters) unless IndividualName is mapped. |
Field | PhoneNumber | Phone | Optional. On the shipping address it is the shipping phone. On the billing address it is sent as the customer's phone (up to 20 characters) when the customer's Phone is blank, and otherwise kept in the Stripe customer's metadata. A phone blanked in iPaaS.com after it was sent is cleared in Stripe. |
Field | PostalCode | PostalCode | Recommended. Postal or ZIP code. |
Field | Region | State | Recommended. State, province or region. |
Error Handling
Errors appear in iPaaS.com Dashboard / Integration Monitoring / Error Logs. Every Stripe error code is described in Stripe Error Messages.
STRP-VALD-1004: "Customer …: no valid email (it is blank or has no @)." Give the customer a valid email, then resend it.
STRP-VALD-1012: "Customer …: the billing (or shipping) address country "…" is not a 2-letter country code, so nothing was sent to Stripe." Store a two-letter code (US, CA, GB) on the address, or add a translation on the Country mapping that turns country names into codes, then resend. The same code is used when Balance or NextInvoiceSequence isn't a whole number, or a TaxIdData entry isn't type:value; correct the value the message names.
STRP-BIZL-1012 (two or more Stripe customers can't be told apart). Delete or re-email the extra Stripe customers in the Stripe Dashboard, then retry.
STRP-BIZL-1008: "Stripe customers aren't deleted from iPaaS.com." A Delete collection for customers sent a customer delete. Turn off or remove that collection; customers aren't deleted in Stripe.
STRP-BIZL-1011: "This record moves with its transaction or customer, never on its own." The address collection was added as a collection of its own. Remove that collection, and send the customer instead.
STRP-EXTN-1004 (Stripe refused the request). The message quotes Stripe's reason. Act on it, then resend.
STRP-EXTN-1003 (Stripe rate limit) and STRP-EXTN-1002 (Stripe temporarily unavailable). Nothing; the transfer is retried.
STRP-AUTH-1002 (Secret Key refused) and STRP-AUTZ-1001 (restricted key lacks a permission). Create the key again in Stripe, or add the permission the message names, and update Secret Key.
Testing and Validation
Test Scenarios
Create an iPaaS.com customer that isn't linked to Stripe. Confirm nothing is sent and no error is logged.
With the every-customer filter, create an iPaaS.com customer with an email no Stripe customer has, a name and a primary billing address. Confirm a new Stripe customer is created with the joined name, the email and the address, and that its Stripe id is saved as the external ID.
Change a linked customer's last name in iPaaS.com. Confirm the Stripe customer's name is updated and no second Stripe customer is created.
Add a primary shipping address with a phone. Confirm the Stripe customer's shipping address carries the name and phone.
Give a linked customer a primary billing address with a phone and a comment, and send it. Blank the phone and the comment in iPaaS.com. Confirm the next update clears the phone and description in Stripe.
Set a customer's billing address country to USA. Confirm STRP-VALD-1012 names the value and nothing changed in Stripe; change it to US and confirm the customer is sent.
Create two Stripe customers with the same email, then send an iPaaS.com customer with that email whose link was removed (it still has a Stripe Customer ID). Confirm STRP-BIZL-1012 and nothing changed in Stripe.
Run a Manual Sync with a linked iPaaS.com customer id. Confirm it updates the same Stripe customer.
Validation Checklist
customer/created and customer/updated are subscribed under Outbound Data Flows.
The filter matches the customers you want sent: linked customers only (the default), or every customer with an email.
The Stripe Customer ID custom field exists.
Countries are stored as two-letter codes.
No Delete mapping is on the collection.
Additional Notes
Payment methods: no card or bank number is sent to Stripe. The payment fields you can map take only the id of something already in Stripe (a payment method, token, source, card or bank account).
Billing doesn't need this collection: an invoice issued FROM iPaaS.com finds or creates its own Stripe customer.
Related Documents
Related Mapping Documentation
