Skip to main content

iPaaS.com to Stripe Customer Mapping Documentation

How the Stripe integration keeps Stripe customers up to date FROM iPaaS.com, with their name, email, description and billing and shipping addresses, finding the Stripe customer by its link, its iPaaS.com id or its email before creating one.

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

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

  1. 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).

  2. 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).

  3. The Stripe customer is found (see Customer Matching) or created. Nothing has to be transferred first.

  4. 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).

  5. 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

Email

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

return ((FirstName ?? "") + " " + (LastName ?? "")).Trim();

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

  1. Create an iPaaS.com customer that isn't linked to Stripe. Confirm nothing is sent and no error is logged.

  2. 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.

  3. 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.

  4. Add a primary shipping address with a phone. Confirm the Stripe customer's shipping address carries the name and phone.

  5. 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.

  6. 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.

  7. 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.

  8. 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

Did this answer your question?