curl --request POST \
  --url https://app.sideshift.app/api/v1/invoices \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "customerName": "Acme Co.",
  "customerEmail": "billing@acme.example",
  "paymentType": "one_time",
  "currency": "usd",
  "dueDate": "2026-06-15",
  "collectCustomerFee": true,
  "allowedPaymentTypes": [
    "card"
  ],
  "lineItems": [
    {
      "description": "Q2 retainer",
      "quantity": 1,
      "unitPriceCents": 250000
    }
  ]
}
'

{
  "invoice": {
    "id": "<string>",
    "invoiceNumber": "<string>",
    "status": "open",
    "customerId": "<string>",
    "customerName": "<string>",
    "customerEmail": "jsmith@example.com",
    "additionalEmails": [
      "jsmith@example.com"
    ],
    "customerAddress": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "country": "<string>"
    },
    "paymentType": "one_time",
    "currency": "<string>",
    "lineItems": [
      {
        "description": "<string>",
        "quantity": 2,
        "unitPriceCents": 2,
        "id": "<string>",
        "amountCents": 123
      }
    ],
    "subtotalCents": 123,
    "taxCents": 123,
    "discountCents": 123,
    "totalCents": 123,
    "allowedPaymentTypes": [
      "<string>"
    ],
    "collectCustomerFee": true,
    "issueDate": "2023-11-07T05:31:56Z",
    "dueDate": "2023-11-07T05:31:56Z",
    "paidAt": "2023-11-07T05:31:56Z",
    "voidedAt": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "notes": "<string>",
    "terms": "<string>",
    "sendReminders": true,
    "remindersSentCount": 123,
    "lastReminderSentAt": "2023-11-07T05:31:56Z",
    "hostedInvoiceUrl": "<string>",
    "pdfUrl": "<string>",
    "bankTransferInstructions": {
      "type": "us_bank_transfer",
      "currency": "<string>",
      "reference": "<string>",
      "hostedInstructionsUrl": "<string>",
      "financialAddresses": [
        {
          "bankName": "<string>",
          "accountNumber": "<string>",
          "routingNumber": "<string>",
          "accountHolderName": "<string>",
          "accountHolderAddress": "<string>",
          "accountType": "<string>",
          "iban": "<string>",
          "swiftCode": "<string>"
        }
      ],
      "generatedAt": "2023-11-07T05:31:56Z"
    },
    "bankTransferFeeCents": 123,
    "bankTransferAmountCents": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "url": "<string>"
}

Create and send an invoice

Create an invoice for a customer and (by default) email the hosted payment link to them. Returns the saved invoice along with the hosted payment URL.

Set sendEmail to false if you only want to create the invoice without delivering it. You can email it later via POST /invoices/{invoiceId}/send.

Payment links: set invoiceType to payment_link for a recipient-free checkout link. Payment-link templates are listed alongside regular invoices; reusable links mint a child invoice per payment. Sending email on a payment link returns 409.

All amounts are integer cents (unitPriceCents, taxCents, discountCents).
dueDate must be an ISO 8601 date or date-time string.
allowedPaymentTypes defaults to ["card"]. See the schema for supported values.
Card and Plaid-ACH payments are handled by the card and us_bank_account methods (Whop checkout). Use those for any flow that pulls funds from the customer’s account.
BNPL (pay over time): including one or more BNPL values (see the allowedPaymentTypes enum — klarna, affirm, afterpay_clearpay, sezzle, zip, card installments, and more) lets the payer choose Pay now / Pay over time on the hosted invoice page. BNPL payments are processed by Whop. The payer is charged the invoice total unchanged; the merchant’s net proceeds are reduced by a 16% merchant fee when the payer pays over time. Each BNPL option is shown only when the provider is enabled for the account, supports the invoice currency, and the invoice total is within the provider’s supported amount range. Renewal invoices do not offer BNPL.
Including bank_transfer provisions a Stripe virtual bank account dedicated to wire transfers. The response will include bankTransferInstructions with a unique account number, routing number, and reference code (USD, EUR, GBP, JPY, or MXN). We never link out to a Stripe-hosted page — render the fields inline in your UI / email / PDF. The customer must include the reference string in the wire memo so Stripe can match the inbound payment to the correct invoice.
Wire fee: invoices that include bank_transfer carry a 1% platform fee on top of totalCents. The customer wires bankTransferAmountCents (totalCents + bankTransferFeeCents); the merchant is credited only totalCents. Card and ACH rails do not include this fee.
If Stripe Customer Balance is not yet enabled on the account when the invoice is created, bankTransferInstructions will be null on the create response. They self-heal — the next call to GET /invoices/{invoiceId} will lazily provision and persist the virtual receiving account.

POST

invoices

curl --request POST \
  --url https://app.sideshift.app/api/v1/invoices \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "customerName": "Acme Co.",
  "customerEmail": "billing@acme.example",
  "paymentType": "one_time",
  "currency": "usd",
  "dueDate": "2026-06-15",
  "collectCustomerFee": true,
  "allowedPaymentTypes": [
    "card"
  ],
  "lineItems": [
    {
      "description": "Q2 retainer",
      "quantity": 1,
      "unitPriceCents": 250000
    }
  ]
}
'

{
  "invoice": {
    "id": "<string>",
    "invoiceNumber": "<string>",
    "status": "open",
    "customerId": "<string>",
    "customerName": "<string>",
    "customerEmail": "jsmith@example.com",
    "additionalEmails": [
      "jsmith@example.com"
    ],
    "customerAddress": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "country": "<string>"
    },
    "paymentType": "one_time",
    "currency": "<string>",
    "lineItems": [
      {
        "description": "<string>",
        "quantity": 2,
        "unitPriceCents": 2,
        "id": "<string>",
        "amountCents": 123
      }
    ],
    "subtotalCents": 123,
    "taxCents": 123,
    "discountCents": 123,
    "totalCents": 123,
    "allowedPaymentTypes": [
      "<string>"
    ],
    "collectCustomerFee": true,
    "issueDate": "2023-11-07T05:31:56Z",
    "dueDate": "2023-11-07T05:31:56Z",
    "paidAt": "2023-11-07T05:31:56Z",
    "voidedAt": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "notes": "<string>",
    "terms": "<string>",
    "sendReminders": true,
    "remindersSentCount": 123,
    "lastReminderSentAt": "2023-11-07T05:31:56Z",
    "hostedInvoiceUrl": "<string>",
    "pdfUrl": "<string>",
    "bankTransferInstructions": {
      "type": "us_bank_transfer",
      "currency": "<string>",
      "reference": "<string>",
      "hostedInstructionsUrl": "<string>",
      "financialAddresses": [
        {
          "bankName": "<string>",
          "accountNumber": "<string>",
          "routingNumber": "<string>",
          "accountHolderName": "<string>",
          "accountHolderAddress": "<string>",
          "accountType": "<string>",
          "iban": "<string>",
          "swiftCode": "<string>"
        }
      ],
      "generatedAt": "2023-11-07T05:31:56Z"
    },
    "bankTransferFeeCents": 123,
    "bankTransferAmountCents": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "url": "<string>"
}

Authorizations

x-api-key

string

header

required

API key for authentication. Get yours from Settings → Integrations. A key created by a team member acts as that member and follows their current team permissions; a request outside those permissions returns 403 { "error": "insufficient_scope", "scope": "<required>" }.

Body

application/json

lineItems

object[]

required

Minimum array length: 1

Show child attributes

dueDate

string

required

ISO 8601 date (YYYY-MM-DD) or date-time string.

invoiceType

enum<string>

default:email_invoice

email_invoice (default) creates a recipient-bound invoice. payment_link creates a shareable checkout link with no recipient — omit customer fields; the payer supplies them at checkout.

Available options:

email_invoice,

payment_link

customerId

string | null

Optional existing customer ID. A new customer record is created if omitted. Rejected when invoiceType is payment_link.

customerName

string

customerEmail

string<email>

additionalEmails

string<email>[]

Extra recipients copied on the invoice email.

customerAddress

object

Show child attributes

paymentType

enum<string>

default:one_time

Available options:

one_time,

renewal

currency

string

default:usd

3-letter ISO 4217 currency code (lowercase).

taxCents

integer

default:0

Required range: x >= 0

discountCents

integer

default:0

Required range: x >= 0

collectCustomerFee

boolean

default:true

Whether processing fees are added on top of the customer's total.

allowedPaymentTypes

enum<string>[]

Payment rails the invoice should accept. Order is non-significant.

Pay-now values (card / wallet / Plaid ACH / crypto) are processed by Whop's hosted checkout. The BNPL rails (klarna, affirm, afterpay_clearpay, scalapay, sunbit, zip, sezzle, splitit, claritypay, tamara, sequra, kueski, addi, oney_3x, oney_4x, and the card_installments_* values) are also processed by Whop: the payer still pays totalCents, but SideShift deducts a 16% merchant fee from the amount credited to the merchant when the payer chooses to pay over time. A BNPL option only appears to the payer when the provider is enabled for the account, supports the invoice currency, and the invoice total falls within the provider's supported amount range; ineligible BNPL methods are filtered out without affecting the other payment methods. BNPL applies to one-time invoices only; renewal invoices exclude BNPL rails.

bank_transfer is special: it provisions a Stripe Customer Balance virtual receiving account dedicated to wire transfers (USD, EUR, GBP, JPY, MXN). Customers wire totalCents plus a 1% platform fee; the merchant is credited only totalCents. ACH pulls remain on the us_bank_account rail. We never link out to a Stripe-hosted page.

Available options:

card,

apple_pay,

google_pay,

link,

us_bank_account,

sepa_debit,

bacs_debit,

acss_debit,

au_becs_debit,

cashapp,

paypal,

venmo,

klarna,

affirm,

afterpay_clearpay,

scalapay,

sunbit,

zip,

sezzle,

splitit,

claritypay,

tamara,

sequra,

kueski,

addi,

oney_3x,

oney_4x,

card_installments_three,

card_installments_six,

card_installments_twelve,

crypto,

bank_transfer

description

string | null

notes

string | null

terms

string | null

sendReminders

boolean

default:true

Whether to send automatic past-due reminders.

sendEmail

boolean

default:true

Send the hosted payment link by email immediately on create.

Response

Invoice created

invoice

object

Show child attributes

url

string

Hosted payment URL for the customer

Overview

Guides

OAuth 2.1 & MCP

Legacy API (Deprecated)

Create and send an invoice

Authorizations

Body

Response