Skip to main content

iPaaS.com to Stripe Invoice Mapping Documentation

How the Stripe integration bills iPaaS.com orders and invoices paid on account: it finds or creates the Stripe customer, issues a Stripe invoice with a pay link, re-issues it when the transaction changes, and voids it when cancelled or deleted.

Contents

Summary

Stripe invoices can be issued from iPaaS.com orders and invoices that are paid on account, through outbound transaction events and Manual Sync. For each one the integration finds or creates the customer in Stripe and issues a Stripe invoice for what is still owed, which Stripe emails to the customer with a link to pay online. Tax, shipping and the order discount are added as their own lines, so the Stripe invoice totals exactly what iPaaS.com says is owed. By default Stripe doesn't calculate tax or take discounts on these invoices; you can instead map Stripe's own tax or discounts (see Stripe tax and discounts under Mappings), and the invoice is still only sent when Stripe's amount is the transaction's Total.

When the transaction changes before it is paid, the open invoice is voided and re-issued; when it is cancelled or deleted, the open invoice is voided. The pay link, the invoice's status and its payments are written back to the transaction through Update Stripe Invoice TO iPaaS.com (see Stripe to iPaaS.com Invoice Mapping Documentation).

ID Format

Manual Sync ID Format

Enter the iPaaS.com transaction id on the iPaaS.com Manual Sync page, for example 178816.

External ID Format

iPaaS.com saves the transaction number as the external ID on its own external-ID record. The Stripe invoice carries the iPaaS.com transaction id and this subscription in its metadata, and its id is written back to the Stripe Invoice ID custom field, which is how a later send finds it. Sending the same transaction twice never makes a second invoice. The Stripe invoice number is the transaction number, for example SO-1001 (an example number); a re-issued invoice adds -R1, -R2 and so on.

Deleted Record Support

Supported through Delete Stripe Invoice FROM iPaaS.com. When a transaction linked to a Stripe invoice is deleted in iPaaS.com, its open unpaid Stripe invoice is voided and a draft is deleted, so the customer can't pay an invoice for a transaction that no longer exists. A paid invoice is never touched; refund it in Stripe if needed. Deleting a transaction never deletes its Stripe customer.

A deleted transaction can't be read back, so its invoice is found by searching Stripe for this subscription's invoice with the transaction's number. Stripe's search can take up to a minute to show a new invoice; when it shows nothing yet, the transfer fails with STRP-NFND-1002 and is retried automatically.

Custom Field Support

The Stripe Invoice ID, Stripe Pay Link, Stripe Invoice Status, Stripe Amount Paid and Stripe Message custom fields must exist on iPaaS.com transactions: they are written back by Update Stripe Invoice TO iPaaS.com, and this collection's filter reads Stripe Invoice ID to tell whether a transaction is already linked to a Stripe invoice. Formulas can read any iPaaS.com custom field on the transaction with GetCustomFieldValue, as the filter does. iPaaS.com custom fields are not sent to Stripe as metadata.

Mapping Collection Status

  • Status: Enabled.

  • Trigger Events: subscribe to transaction/created and transaction/updated under the subscription's Outbound Data Flows, and to transaction/deleted for Delete Stripe Invoice FROM iPaaS.com. No transaction transfers automatically until you subscribe. Manual Sync is available by iPaaS.com transaction id. The line child collection transfers with the transaction.

Duplicate or Conflicting Mappings

  • Delete Stripe Invoice FROM iPaaS.com handles a deleted transaction (see Deleted Record Support).

  • Update Stripe Invoice TO iPaaS.com writes the invoice's state back to the same transaction. It writes only the Stripe fields, the status when the invoice is paid in full, and the payment lines, so the two don't overwrite each other's values.

  • Add/Update Stripe Customer FROM iPaaS.com keeps Stripe customers up to date. It is optional for billing: an invoice finds or creates its own Stripe customer.

Invoice and Customer Matching

The collection has no Collision Handling Method; the integration matches automatically.

  • The invoice: a later send finds the transaction's invoice by its Stripe Invoice ID, else by searching Stripe for this subscription's invoice for the transaction. An unchanged transaction sends nothing; a changed one voids the open invoice and issues a re-issue.

  • The customer: the Stripe customer linked to the iPaaS.com customer, else the one carrying its iPaaS.com customer id, else the one with the transaction's email; otherwise a new Stripe customer is created. When two or more Stripe customers have the email and none is linked to the iPaaS.com customer, nothing is sent and the transfer is refused with STRP-BIZL-1012.

Supported Child Collections

  • Add/Update Stripe Invoice Line FROM iPaaS.com (Transaction Line): the transaction's lines, sent as the invoice's lines.

System Caveats

Stripe Caveats

  • Invoice numbers: Stripe allows 26 characters; the integration takes 22 so a re-issue can add -R1. A number already used by another Stripe invoice is refused by Stripe.

  • Invoice emails: with Stripe Emails Invoices set to Yes (the default), Stripe emails each new invoice to the customer.

  • Due date: the invoice is due Invoice Days Until Due days after issue (default 30) unless a due date is mapped.

  • Changes after issue: a change to the memo, customer name or phone after the invoice is issued doesn't reach the issued invoice; a change to the lines or total re-issues it.

  • Paid or credited in Stripe: a change from iPaaS.com no longer changes the invoice; adjust it in Stripe with a credit note or refund.

  • Rate limiting: when Stripe asks the integration to slow down, the transfer is rescheduled automatically and resumes after the wait. No action is needed.

iPaaS.com Caveats

  • Lines must add up: the lines plus tax and shipping, less the discount, must equal the transaction's Total, or nothing is sent. When Stripe calculates the tax or discounts, the amount Stripe calculates must equal the Total, or the invoice is voided before it reaches the customer.

  • The on-account Payment Method: only a transaction with a payment on your on-account (pay later) Payment Method is billed, and the same name must be set in the filter and in the BalanceDue mapping.

  • Child collections move with the transaction: don't add the line 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.

  • Invoice emails: with Stripe Emails Invoices set to Yes, the integration asks Stripe to email each new invoice; Stripe sends no invoice emails from a test key.

iPaaS.com Configuration

  • Settings: Stripe Emails Invoices, Invoice Days Until Due and Close Stripe Invoices Paid Elsewhere (see Stripe Connections and Settings).

  • Outbound Data Flows: subscribe to transaction/created, transaction/updated and transaction/deleted.

  • Custom fields: the five custom fields listed under Custom Field Support.

  • Placeholders: replace the on-account Payment Method in the filter and in BalanceDue before the first transfer.

Integration Flow

  1. A transaction event or a Manual Sync sends an iPaaS.com transaction. It passes the collection's filter only when it is an order or invoice paid on account, or is already linked to a Stripe invoice.

  2. The transaction is checked first: it must have a number of at most 22 characters, a valid email, at least one line, and lines that add up to the total. A transaction that fails a check is refused with a coded error, and nothing is sent to Stripe.

  3. The Stripe customer is found (by the link, the iPaaS.com customer id it carries, or the email) or created. Nothing has to be transferred first.

  4. For a new invoice, one Stripe line is added per transaction line, plus tax, shipping, discount and any payment already received outside Stripe; the invoice is then finalized and Stripe is asked to send it (unless Stripe Emails Invoices is No).

  5. On a later send: an unchanged transaction sends nothing; a changed one voids the open invoice and issues a re-issue (-R1, -R2…); a cancelled one voids it; a balance of 0 marks an open invoice paid outside Stripe when Close Stripe Invoices Paid Elsewhere is Yes.

  6. The integration queues Update Stripe Invoice TO iPaaS.com for the invoice, which writes the pay link and status back onto the transaction.

Mappings

Add/Update Stripe Invoice FROM iPaaS.com

iPaaS.com data type: Transaction

Mapping Filter

// Which transactions get a Stripe invoice: those owed on account (terms). Before turning this collection on, put your
// on-account payment method's name on the next line exactly as in iPaaS.com (for example A/R), and the same name in the
// BalanceDue mapping. Until then nothing is invoiced.
var onAccountMethod = "REPLACE with your on-account payment method";
if (onAccountMethod.StartsWith("REPLACE")) return false;
// Only sales are billed: an order or an invoice. A return, quote or any other type never gets a Stripe invoice.
if (Type != "Order" && Type != "Invoice") return false;
// A transaction already linked to a Stripe invoice is always sent, so changes, cancellations and payments made elsewhere reach Stripe.
if (("" + GetCustomFieldValue(CustomFields, "Stripe Invoice ID")).Length > 0) return true;
var method = onAccountMethod.Replace("/", "").Trim().ToUpper();
var onAccount = Payments != null && Payments.Any(p => p.Method != null && p.Method.Replace("/", "").Trim().ToUpper() == method);
var paid = Payments == null ? 0 : Payments.Where(p => p.Status != "Voided" && p.Method != null && p.Method.Replace("/", "").Trim().ToUpper() != method).Sum(p => p.Amount);
return Status != "Cancelled" && onAccount && Total - paid > 0;

Filter Description: a transaction is sent when all of these hold, and is otherwise skipped with no error:

  • The on-account Payment Method (onAccountMethod) has been set. Until it is, nothing is sent, not even a transaction already linked to a Stripe invoice, and no error is logged.

  • Its Type is Order or Invoice; a return, quote or any other type is never billed.

  • It is already linked to a Stripe invoice (its Stripe Invoice ID custom field has a value): then it is always sent, so changes, cancellations and payments made elsewhere reach Stripe.

  • Otherwise it is not Cancelled, it has a payment with the on-account Payment Method (onAccountMethod, compared without slashes, spaces or letter case), and its Total less the other non-voided payments is more than 0.

Placeholder value — replace during implementation: "REPLACE with your on-account payment method" (the value of onAccountMethod). Replace it with the name of your on-account (pay later) Payment Method exactly as it is named in iPaaS.com, for example A/R or On Account, here and in the BalanceDue mapping. Until you do, this collection sends nothing and logs no error.

Description: issues, re-issues or voids the Stripe invoice for an iPaaS.com transaction paid on account.

Mapping Type

Source Field (iPaaS.com)

Destination Field (Stripe)

Description

Dynamic Formula

The BalanceDue formula, shown in full after this table

BalanceDue

Recommended. What the customer still owes after payments made outside Stripe. An invoice paid in part outside Stripe is issued for the remainder, with a "Payment already received" line. At 0, no invoice is issued, and an open unpaid invoice is marked paid outside Stripe when Close Stripe Invoices Paid Elsewhere is Yes.

Field

EmailAddress

CustomerEmail

Required. Stripe finds or creates its customer by this email, and emails the invoice to it. A blank email, or one without an @, is refused before anything reaches Stripe.

Dynamic Formula

var a = Addresses == null ? null : (Addresses.FirstOrDefault(x => x.IsPrimaryBilling == true) ?? Addresses.FirstOrDefault()); return a == null ? null : (!string.IsNullOrEmpty(a.Company) ? a.Company : (a.FirstName + " " + a.LastName).Trim());

CustomerName

Recommended. The name on the Stripe customer when the integration creates it: the company on the primary billing address (or the first address), else that address's first and last name. A name changed after the invoice is issued doesn't reach Stripe.

Field

DiscountAmount

DiscountAmount

Recommended. An order-level discount, as a positive amount, added as a negative "Discount" line.

Field

CustomerId

IpaasCustomerId

Recommended. The iPaaS.com customer id, kept on the Stripe customer so later invoices find the same Stripe customer even if its email changes.

Field

Id

IpaasTransactionId

Required. The iPaaS.com transaction id, kept on the Stripe invoice: it ties the invoice to the transaction, and makes a transfer sent twice change nothing.

Field

ShippingAmount

ShippingAmount

Recommended. The shipping charge, added as a "Shipping" line.

Field

Status

Status

Recommended. Cancelled voids the open Stripe invoice (a draft is deleted). A paid invoice is left as it is, with a message on the transaction to refund it in Stripe if needed.

Field

TaxAmount

TaxAmount

Recommended. The tax, added as a "Tax" line. By default Stripe doesn't calculate tax on these invoices (see Stripe Tax and Discounts below).

Field

Total

Total

Required. The amount the customer owes. The lines plus tax and shipping, less the discount, must equal it. With the template's filter, a new transaction whose total (less what is already paid) is 0 or less isn't sent, with no error (STRP-VALD-1002 if you change the filter to let it through); on a transaction with an open invoice, it takes that invoice out of use.

Field

TransactionNumber

TransactionNumber

Required. The Stripe invoice number the customer sees, at most 22 characters.

BalanceDue formula:

// What is still owed after payments made outside Stripe: the total less every payment that isn't voided, on account or from Stripe.
// Put your on-account payment method's name on the next line, the same as in this collection's filter. Until then this is
// left empty, and no Stripe invoice is closed as paid elsewhere.
var onAccountMethod = "REPLACE with your on-account payment method";
if (onAccountMethod.StartsWith("REPLACE")) return null;
var method = onAccountMethod.Replace("/", "").Trim().ToUpper();
return Total - (Payments == null ? 0 : Payments.Where(p => p.Status != "Voided" && p.Method != null && p.Method.Replace("/", "").Trim().ToUpper() != method && (p.Description == null || !p.Description.StartsWith("Stripe "))).Sum(p => p.Amount));

Placeholder value — replace during implementation: "REPLACE with your on-account payment method", the same value as in the filter. Until you replace it, BalanceDue is left empty: an invoice asks for the whole total even when part was paid outside Stripe, and no Stripe invoice is closed as paid elsewhere. If the name doesn't match your Payment Method, the on-account payment counts as already paid, so the balance comes out as 0 and the customer is never asked to pay.

Other Stripe Invoice Fields You Can Map

The template doesn't map these; add a mapping only when you need one. A field that isn't mapped sends nothing, and Stripe checks each value sent (a value Stripe refuses fails the transfer with STRP-EXTN-1004, quoting Stripe's reason).

Destination Field (Stripe)

Description

Memo

The memo shown on the Stripe invoice.

Footer

The footer printed on the Stripe invoice, at most 5,000 characters.

StatementDescriptor

The text on the customer's card statement when they pay, at most 22 characters.

EffectiveAt

The invoice date printed on the invoice and its receipt: a day (for example 2026-11-15, taken at noon in the time zone of the Stripe account), a date and time, or a Unix time. Blank: the day Stripe issues it.

AutomaticallyFinalizesAt

When Stripe would finalize a draft by itself. The integration finalizes each invoice as soon as it is made, so this rarely matters.

DefaultPaymentMethod

A Stripe payment method (pm_…) suggested for paying the invoice.

DefaultSource

An older kind of Stripe payment source (card_…, ba_…, src_…) suggested for paying the invoice.

AccountTaxIds

Your own tax ids in Stripe (txi_…, separated by commas), printed on the invoice.

BillingSubscriptionId

A Stripe subscription (sub_…) the invoice and its lines belong to.

CustomerAccount

For Stripe accounts that bill customer accounts: the account billed, sent with the invoice and each line.

OnBehalfOf

Stripe Connect platforms only: the connected account (acct_…) the invoice is issued for.

ApplicationFeeAmount

Stripe Connect platforms only: the platform's fee on the invoice, in the transaction's currency.

AutomaticTax

True asks Stripe Tax to calculate the invoice's tax. Needs Stripe Tax set up in your Stripe account and a Stripe customer whose address Stripe Tax can place. See Stripe Tax and Discounts below.

TaxRateIds

Stripe tax rates (txr_…, separated by commas) applied to the whole invoice. See Stripe Tax and Discounts below.

DiscountCodes

Stripe discounts on the whole invoice, separated by commas: a coupon id, a promotion code id (promo_…) or a discount id (di_…). See Stripe Tax and Discounts below.

Stripe Tax and Discounts

By default the transaction's own TaxAmount and DiscountAmount are sent as lines, and Stripe calculates nothing. To have Stripe calculate the tax instead, map AutomaticTax or TaxRateIds (on the transaction or a line); to have Stripe take discounts off, map DiscountCodes (on the transaction or a line). Because no one can then know the exact amount before Stripe calculates it, the integration protects the customer in three ways:

  • A transaction that carries its own tax amount (TaxAmount) together with Stripe's tax, or its own discount amount (DiscountAmount) together with Stripe's discounts, is refused with STRP-VALD-1006: the tax would be charged, or the discount taken, twice. Nothing is sent.

  • Lines that can't be right are refused before anything is sent (STRP-VALD-1006): with Stripe's tax, lines plus shipping already above the Total; with Stripe's discounts, lines plus tax and shipping already below it.

  • When Stripe has made the invoice, its amount must be the transaction's Total (or BalanceDue). If it isn't, the invoice is voided at once, before it is sent, and the transfer fails with STRP-BIZL-1017, so the customer is never asked for an amount nobody set. A retry of the unchanged transaction gives the same error without making another Stripe invoice for 24 hours after the void; after that, one retry asks Stripe again, so a fix made only in Stripe's tax settings is picked up. Correct the Total or the mapping, then send the transaction again.

With invoice-level DiscountCodes mapped, a discount already on the Stripe customer doesn't apply to the invoice, so it no longer stops the invoice (STRP-BIZL-1015 still refuses a customer with a Stripe balance).

Add/Update Stripe Invoice Line FROM iPaaS.com

iPaaS.com data type: Transaction Line

Description: sends each line of the transaction to its Stripe invoice: what the customer sees (the SKU, then the description), the quantity and the price. The lines are free-text invoice items; they don't need to match Stripe products.

Mapping Type

Source Field (iPaaS.com)

Destination Field (Stripe)

Description

Field

Description

Description

Recommended. What the customer sees for the line, after the SKU. A line needs a SKU or a description; with neither, it is refused. A description longer than 5,000 characters (Stripe's limit) is shortened.

Field

ExtendedPrice

ExtendedPrice

Required. The line's total (quantity × unit price), after any line discount, before tax. The unit price sent to Stripe is ExtendedPrice ÷ Quantity. A UnitPrice mapping can be added instead.

Field

Qty

Quantity

Recommended. How many; blank counts as 1, 0 is a line at no charge, and a negative quantity is refused. A fractional quantity such as 1.5 is sent to Stripe as it is, priced so the line comes to its total.

Field

Sku

Sku

Recommended. Shown before the description on the Stripe invoice line. A line needs a SKU or a description.

Other Stripe Line Fields You Can Map

The template doesn't map these; a field that isn't mapped sends nothing.

Destination Field (Stripe)

Description

PeriodStart and PeriodEnd

The period the line covers, shown on the Stripe invoice line: a day (for example 2026-11-01: PeriodStart from the start of that day, PeriodEnd to its end, in the time zone of the Stripe account), a date and time, or a Unix time. Map both or neither; one alone is refused with STRP-VALD-1011.

TaxCode

The Stripe Tax product tax code of the line (txcd_…), used when Stripe calculates the tax.

PriceIncludesTax

True when the line's price already includes tax, false when tax is added to it. Only matters when Stripe calculates the tax.

TaxRateIds

Stripe tax rates (txr_…, separated by commas) Stripe adds to this line. See Stripe Tax and Discounts above.

DiscountCodes

Stripe discounts on this line: a coupon id, a promotion code id (promo_…) or a discount id (di_…). See Stripe Tax and Discounts above.

Delete Stripe Invoice FROM iPaaS.com

iPaaS.com data type: Transaction

Mapping Filter

// Leave as is: transactions linked to a Stripe invoice.
return ("" + GetCustomFieldValue(CustomFields, "Stripe Invoice ID")).Length > 0;

Filter Description: only a deleted transaction that is linked to a Stripe invoice (its Stripe Invoice ID custom field has a value) is processed; any other deleted transaction is skipped with no error. Leave the filter as it is.

Description: voids the open unpaid Stripe invoice of a deleted transaction, or deletes a draft. This collection has no field mappings: it needs only the transaction.

Error Handling

Errors appear in iPaaS.com Dashboard / Integration Monitoring / Error Logs. Every Stripe error code is described in Stripe Error Messages. The checks below run before anything is sent to Stripe.

  • STRP-VALD-1001 (no transaction number) and STRP-VALD-1005 (transaction number too long). Map TransactionNumber, and keep numbers to 22 characters.

  • STRP-VALD-1002 (nothing to collect). The total is 0 or less on a transaction with no Stripe invoice. Nothing is needed unless the total is wrong.

  • STRP-VALD-1004: "Transaction … has no valid customer email (it is blank or has no @)." Give the transaction a valid email, then resend it.

  • STRP-VALD-1006 (lines don't add up to the Total). The message names both amounts. Correct the lines, tax, shipping or discount, then resend. The same code refuses the transaction's own TaxAmount or DiscountAmount mapped together with Stripe's tax or discounts: map one or the other.

  • STRP-VALD-1009: "Transaction …: map the iPaaS.com transaction Id to IpaasTransactionId." Restore the IpaasTransactionId mapping.

  • STRP-VALD-1010: "Transaction … has no lines." Add lines, or check the Add/Update Stripe Invoice Line FROM iPaaS.com collection is turned on.

  • STRP-VALD-1011: "Transaction …, line …: …" A line has no SKU or description, no price, a negative quantity, or only one of PeriodStart and PeriodEnd. The message names the line and what to map.

  • STRP-BIZL-1017 (Stripe's tax or discounts came to another amount). The Stripe invoice was voided before it was sent. Make the Total match what Stripe calculates, or map TaxAmount and DiscountAmount instead of Stripe's, then resend.

  • 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-1010 (paid in full outside Stripe, but Close Stripe Invoices Paid Elsewhere is off). Written to the transaction's Stripe Message; the Stripe invoice stays open. Turn the setting on, or close the invoice in Stripe.

  • STRP-NFND-1002 (deleted transaction's invoice not found yet). Nothing; the delete is retried and the invoice is still voided. If it keeps failing, void the invoice in Stripe.

  • STRP-EXTN-1004 (Stripe refused the request). The message quotes Stripe's reason, for example an invoice number already used. 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.

A transaction that fails the filter (a card-paid order, a return, a cancelled transaction never invoiced) transfers nothing and is not an error.

Testing and Validation

Test Scenarios

  1. Create an order in iPaaS.com with an on-account payment, a valid email, two lines, tax and shipping. Confirm one Stripe invoice is issued with the transaction number, one line per transaction line plus Tax and Shipping lines, and a total equal to the order's; and that Stripe Invoice ID and Stripe Pay Link appear on the transaction.

  2. Send the same transaction again unchanged. Confirm no second invoice is made.

  3. Change a line's price before the invoice is paid. Confirm the open invoice is voided and a re-issue numbered with -R1 is issued for the new total.

  4. Set the transaction to Cancelled. Confirm the open invoice is voided.

  5. Send a transaction whose lines don't add up to the total. Confirm STRP-VALD-1006 and nothing in Stripe.

  6. Delete a transaction whose invoice is open. Confirm the invoice is voided.

  7. Run a Manual Sync with an iPaaS.com transaction id. Confirm it updates the same invoice.

Validation Checklist

  • The on-account Payment Method is set in the filter and in BalanceDue (no "REPLACE with" value is left).

  • transaction/created, transaction/updated and transaction/deleted are subscribed under Outbound Data Flows.

  • The five custom fields exist.

  • Stripe Emails Invoices, Invoice Days Until Due and Close Stripe Invoices Paid Elsewhere are set as you want.

Additional Notes

  • Card payments in iPaaS.com: an order already paid in full by card isn't billed. The customer pays on Stripe's page; no card data passes through iPaaS.com.

  • Refunds and credit notes are made in Stripe, not from iPaaS.com.

  • Initial load: existing transactions are sent only when they are created or updated after the integration is set up, or through Manual Sync.

  • Changes after issue: see Stripe Integration Known Limitations for what an issued invoice keeps.

Related Documents

Related Mapping Documentation

Did this answer your question?