Sign in

v1

latestOpenAPI 3.0.02026-07-2475182625.5 KB
Invoices

Create an invoice

Creates and finalizes a new invoice with custom contacts, items, pricing, and optional payment configuration.

This endpoint returns a detailed invoice object, including totals, payment URLs, and contact metadata, based on the request body provided.

post/invoices/paymentInvoice

Request body

currencyCodestring required

ISO 4217 currency code used for the invoice.

languageCodestring

Language/locale code for the invoice.

autoConvertPaymentCurrencyboolean

Whether to auto-convert the currency based on the buyer’s location.

dueDatestring date-time

When the invoice is due (ISO 8601 format).

invoiceNotestring

Optional non-structured note for internal or customer use.

paymentMethodstring required

Payment method to use. Common values include CARD, PAYPAL, WIRE, ACH. Refer to FastSpring dashboard for the full list of supported methods.

mode'TEST' | 'LIVE' required

Mode used to create the invoice (test or live).

tagsJsonstring

Stringified JSON object of key-value pairs to attach as metadata to this invoice. Values may be strings or arrays of strings. Must be serialized as a JSON string (not a nested object). Stored on the invoice and returned in both POST and GET responses.

Example request

{
  "currencyCode": "USD",
  "languageCode": "en",
  "autoConvertPaymentCurrency": true,
  "contacts": [
    {
      "contactType": "deliverTo",
      "contact": {
        "email": "recipient@example.com",
        "firstName": "John",
        "lastName": "Smith",
        "phoneNumber": "+1 555 000-0001",
        "companyName": "Example Company",
        "website": "https://example.com",
        "fullName": "John Smith"
      },
      "address": {
        "addressLine1": "123 Main Street",
        "addressLine2": "Suite 100",
        "city": "Metropolis",
        "region": "CA",
        "postalCode": "12345",
        "country": "US"
      },
      "organization": {
        "organizationName": "Example Company",
        "organizationType": "S Corporation",
        "organizationReference": "ORG-001"
      }
    }
  ],
  "dueDate": "2026-12-01T00:00:00Z",
  "invoiceNote": "Sample invoice note for reference.",
  "invoiceItems": [
    {
      "productPath": "sample-product",
      "quantity": 4,
      "sku": "SKU-123",
      "useCatalogPricing": true,
      "display": "Sample Product Display Name",
      "summary": "Short product summary here.",
      "extendedItemDescription": "This subscription renews automatically each year unless canceled."
    }
  ],
  "paymentMethod": "CARD",
  "mode": "TEST",
  "tagsJson": "{\"costCenter\": \"CC-1042\", \"purchaseOrder\": \"PO-2026-Q2-0042\"}"
}

Response

OK

idstring

Unique identifier for the invoice.

acquisitionTransactionIdstring

ID of the transaction that created the invoice.

companyNamestring

Name of the company or user issuing the invoice.

createdOnstring date-time

Date and time when the invoice was created.

currencystring

ISO 4217 currency code.

dueDatestring date-time

Invoice due date.

status'CANCELED' | 'OPEN' | 'PAYMENT_ACCEPTED' | 'COMPLETE' | 'PAID' | 'PENDING' | 'VOID'

Invoice lifecycle status (uppercase).

  • OPEN: Awaiting finalization
  • PENDING: Awaiting payment
  • PAYMENT_ACCEPTED: Payment processing
  • COMPLETE: Fully completed
  • PAID: Legacy status (deprecated, use COMPLETE)
  • CANCELED: Canceled before completion
  • VOID: Voided after completion
languagestring

Language used for invoice content.

invoiceSecretstring

Secure token to view the invoice.

invoiceType'CREDIT_MEMO' | 'INVOICE' | 'FULL_TAX_REFUND' | 'PARTIAL_REFUND' | 'FULL_REFUND' | 'PAYMENT_INVOICE'

Invoice classification type

orderReferencestring

External reference for the order.

shippingTotalnumber

Total shipping cost.

subTotalnumber

Subtotal amount before tax and discounts.

siteIdstring

FastSpring site ID.

taxRatenumber

Tax rate applied to the invoice.

taxTypestring

Type of tax applied.

totalOrderValuenumber

Final order value after taxes and discounts.

totalDiscountValuenumber

Total discounts applied to the invoice.

totalTaxValuenumber

Total tax applied to the invoice.

versionstring

Invoice version number.

notesstring

Invoice notes for internal or customer reference.

paymentInvoiceWebLinkstring

Web URL to view the invoice.

paymentInvoicePdfLinkstring

Direct download URL for invoice PDF.

paymentInvoiceWebPayLinkstring

Payable session link for this invoice. The session remains valid until the expiration date, calculated as the payment due date plus the configured grace period. After expiration, the link is no longer payable, and a new session must be generated.

paymentCurrencyCodestring

Currency used for invoice payment.

paymentOrderReferencestring

Order reference used in payment flow.

paymentDueDatestring date-time

Business due date for the invoice (ISO 8601). The invoice remains payable via the session until session expiration, which equals the payment due date plus the grace period.

tagsJsonstring

Stringified JSON metadata tags attached to the invoice at creation. Returned verbatim in the POST response.

Example response

{
  "id": "ABCD0EF1GHIJKLMNOPQRSTUVWXYZ",
  "acquisitionTransactionId": "ABCD0EF1GHIJKLMNOPQRSTUVWXYZ",
  "companyName": "recipient@example.com",
  "createdOn": "2026-04-02T16:08:24Z",
  "currency": "USD",
  "dueDate": "2026-12-31T00:00:00Z",
  "items": [
    {
      "id": "AB0CDE1FGHIJKL2M3N4OPQRS5T6U",
      "acquisitionTransactionItemId": "aB0Cd1E2FGh3Ij-K4LMNop",
      "display": "Sample Product Display Name",
      "invoiceId": "ABCD0EF1GHIJKLMNOPQRSTUVWXYZ",
      "productFormat": "DIGITAL",
      "productPath": "sample-product",
      "productType": "BASE",
      "listPrice": 25,
      "totalPreShippingPrice": 100,
      "itemTaxes": [
        {
          "id": "ABCDEF0G1HI2JK3LMN4OPQRSTU5V",
          "itemId": "AB0CDE1FGHIJKL2M3N4OPQRS5T6U",
          "value": 6,
          "taxRate": 6,
          "taxType": "US_SALES_TAX"
        }
      ],
      "quantity": 4,
      "extendedItemDescription": "Extended product description with additional details."
    }
  ],
  "status": "COMPLETE",
  "language": "en",
  "invoiceSecret": "TAX01ABCDEFGHIJ2KLMNOP3QRSTUV4WXYZABC5DEFGHIJKLMNOPQ",
  "invoiceType": "INVOICE",
  "orderReference": "ABC012345-6789-01234",
  "paymentReceiver": {
    "id": "ABC0DEFGHI1JKL2MN3OPQRS4TUVW",
    "email": "recipient@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "fullName": "John Smith",
    "companyName": "Example Company",
    "phoneNumber": "+1 555 000-0001",
    "website": "https://example.com",
    "contactType": "SHIP-TO"
  },
  "paymentReceiverAddress": {
    "id": "ABC0DEFGHIJKL1MNOP23Q4RSTUVW",
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 100",
    "city": "Metropolis",
    "region": "CA",
    "postalCode": "12345",
    "country": "US"
  },
  "purchaser": {
    "id": "ABC0DEFGHI1JKL2MN3OPQRS4TUVW",
    "email": "recipient@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "fullName": "John Smith",
    "companyName": "Example Company",
    "phoneNumber": "+1 555 000-0001",
    "website": "https://example.com",
    "contactType": "SHIP-TO"
  },
  "purchaserAddress": {
    "id": "ABC0DEFGHIJKL1MNOP23Q4RSTUVW",
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 100",
    "city": "Metropolis",
    "region": "CA",
    "postalCode": "12345",
    "country": "US"
  },
  "purchaserOrganization": {
    "organizationId": "ORGABCDEFGHIJKLMNOPQRST0U1VWX",
    "organizationName": "Example Company",
    "organizationType": "S Corporation",
    "organizationReference": "REF-001"
  },
  "receiver": {
    "id": "ABC0DEFGHI1JKL2MN3OPQRS4TUVW",
    "email": "recipient@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "fullName": "John Smith",
    "companyName": "Example Company",
    "phoneNumber": "+1 555 000-0001",
    "website": "https://example.com",
    "contactType": "SHIP-TO"
  },
  "receiverAddress": {
    "id": "ABC0DEFGHIJKL1MNOP23Q4RSTUVW",
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 100",
    "city": "Metropolis",
    "region": "CA",
    "postalCode": "12345",
    "country": "US"
  },
  "receiverOrganization": {
    "organizationId": "ORGABCDEFGHIJKLMNOPQRST0U1VWX",
    "organizationName": "Example Company",
    "organizationType": "S Corporation",
    "organizationReference": "REF-001"
  },
  "subTotal": 100,
  "siteId": "ABC0DE1GHIJ2",
  "taxRate": 6,
  "taxType": "US_SALES_TAX",
  "totalOrderValue": 106,
  "totalTaxValue": 6,
  "version": "2",
  "notes": "Sample invoice note for reference.",
  "paymentInvoiceWebLink": "https://example.com/account/order/ABC012345-6789-01234/invoice/ABCD0EF1GHIJKLMNOPQRSTUVWXYZ",
  "paymentInvoicePdfLink": "https://example.com/account/order/ABC012345-6789-01234/invoice/ABCD0EF1GHIJKLMNOPQRSTUVWXYZ/pdf",
  "paymentInvoiceWebPayLink": "https://example.com/session/ABC012345-6789-01234/pay",
  "paymentCurrencyCode": "USD",
  "paymentOrderReference": "ABC012345-6789-01234",
  "paymentDueDate": "2026-12-01T00:00:00Z",
  "paymentTotals": {
    "payableTotalDisplay": "$106.00",
    "subTotalDisplay": "$100.00",
    "discountTotalDisplay": "$0.00",
    "taxTotalDisplay": "$6.00",
    "shippingTotalDisplay": "$0.00",
    "taxExemptionReason": "US_SALES_TAX",
    "payableTotal": 106,
    "subTotal": 100,
    "taxTotal": 6
  },
  "tagsJson": "{\"costCenter\": \"CC-1042\", \"purchaseOrder\": \"PO-2026-Q2-0042\"}"
}