---
title: "Create an invoice"
method: POST
path: "/invoices/paymentInvoice"
tags: ["Invoices"]
---

# Create an invoice

`POST /invoices/paymentInvoice`

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.

## Request body

- InvoiceRequest — Payload to create and finalize a payment invoice.
  - `currencyCode` string, required — ISO 4217 currency code used for the invoice.
  - `languageCode` string — Language/locale code for the invoice.
  - `autoConvertPaymentCurrency` boolean — Whether to auto-convert the currency based on the buyer’s location.
  - `contacts` object[], required — Billing and delivery contact details for the invoice.
    - `contactType` 'deliverTo' | 'billTo', required — Role of the contact in the invoice.
    - `contact` object, required
      - `email` string, required — Email address of the contact.
      - `firstName` string, required — First name of the contact.
      - `lastName` string, required — Last name of the contact.
      - `phoneNumber` string — Contact phone number.
      - `companyName` string — Company name associated with the contact.
      - `website` string — Website URL associated with the contact or company.
      - `fullName` string — Optional full name if formatted manually.
    - `address` object
      - `addressLine1` string — Primary street address.
      - `addressLine2` string — Additional address info (suite, floor, etc.).
      - `city` string — City or locality.
      - `region` string — State, province, or region.
      - `postalCode` string — Postal or ZIP code.
      - `country` string — Country code in ISO 3166-1 alpha-2 format.
    - `organization` object — Organization associated with the contact.
      - `organizationName` string — Legal name of the organization.
      - `organizationType` string — Type or classification of the organization.
      - `organizationReference` string — Internal or external reference ID for the organization.
  - `dueDate` string, date-time — When the invoice is due (ISO 8601 format).
  - `invoiceNote` string — Optional non-structured note for internal or customer use.
  - `invoiceItems` object[], required — Line items (products/services) included in the invoice.
    - `productPath` string, required — Product identifier or catalog path.
    - `quantity` integer, required — Number of units purchased.
    - `sku` string — Stock Keeping Unit (SKU) identifier.
    - `useCatalogPricing` boolean, required — Whether to use pricing from the catalog.
    - `display` string — Display name override for this item.
    - `summary` string — Short description of the item.
    - `extendedItemDescription` string — Additional descriptive text displayed below the corresponding line item on the invoice. Useful for including custom details, disclaimers, or item-specific notes that appear directly beneath the product entry.
  - `paymentMethod` string, 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).
  - `tagsJson` string — 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.

## Response `200`

OK

- InvoicePostResponse — Full response returned when retrieving or creating an invoice.
  - `id` string — Unique identifier for the invoice.
  - `acquisitionTransactionId` string — ID of the transaction that created the invoice.
  - `companyName` string — Name of the company or user issuing the invoice.
  - `createdOn` string, date-time — Date and time when the invoice was created.
  - `currency` string — ISO 4217 currency code.
  - `dueDate` string, date-time — Invoice due date.
  - `items` InvoiceItemResponse[] — List of invoice line items.
    - `id` string — Unique identifier for the invoice item.
    - `acquisitionTransactionItemId` string — ID of the original transaction item.
    - `display` string — Display name of the item.
    - `invoiceId` string — ID of the parent invoice.
    - `parentId` string — ID of the parent item, if this is a child item.
    - `childItems` string[] — Array of any child items (usually empty).
    - `productFormat` string — Format of the product (e.g., DIGITAL, PHYSICAL).
    - `productPath` string — Catalog identifier or path for the product.
    - `productType` string — Type of product (BASE, ADD-ON, etc).
    - `listPrice` number — Unit price of the item before tax.
    - `freeTrialPeriod` string — Free trial duration, if applicable.
    - `period` string — Subscription billing period (e.g., monthly).
    - `periodCount` integer — Number of billing periods.
    - `periodEndDate` string, date-time — Date when the billing period ends.
    - `periodPrice` number — Price charged for this billing period.
    - `shippingPrice` number — Cost of shipping applied to this item.
    - `totalPreShippingPrice` number — Item total before shipping and tax.
    - `itemTaxes` object[] — Taxes applied to this item.
      - `id` string — Tax line ID.
      - `itemId` string — ID of the invoice item this tax applies to.
      - `value` number — Amount of tax applied.
      - `taxRate` number — Tax rate percentage.
      - `fromGross` boolean — Whether tax was calculated from gross.
      - `description` string — Optional tax line description.
      - `taxType` string — Type of tax applied.
    - `subscription` boolean — Whether this is a subscription item.
    - `autoRenew` boolean — If this item auto-renews.
    - `taxExempt` boolean — Whether this item is exempt from tax.
    - `quantity` integer — Quantity of the product purchased.
    - `siblingPosition` integer — Position of this item relative to others.
    - `extendedItemDescription` string — Detailed description of the item.
  - `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
  - `language` string — Language used for invoice content.
  - `invoiceSecret` string — Secure token to view the invoice.
  - `invoiceType` 'CREDIT_MEMO' | 'INVOICE' | 'FULL_TAX_REFUND' | 'PARTIAL_REFUND' | 'FULL_REFUND' | 'PAYMENT_INVOICE' — Invoice classification type
  - `orderReference` string — External reference for the order.
  - `paymentReceiver` Contact — Contact details used in invoice communication and processing.
    - `id` string — Unique ID for the contact.
    - `email` string — Email address of the contact.
    - `firstName` string — First name of the contact.
    - `lastName` string — Last name of the contact.
    - `fullName` string — Full name of the contact (if applicable).
    - `companyName` string — Company name this contact represents.
    - `phoneNumber` string — Contact's phone number.
    - `website` string — Website URL for the contact or company.
    - `contactType` string — Role of the contact in the invoice (e.g., SHIP-TO, BILL-TO, PAYMENT_FACILITATOR).
    - `contactServiceId` string — Optional reference to an external service’s contact ID.
    - `contactOrganizationId` string — Optional reference to an external service’s organization ID.
  - `paymentReceiverAddress` Address — Address details used for invoice delivery and billing.
    - `id` string — Unique identifier for the address.
    - `addressLine1` string — Primary street address.
    - `addressLine2` string — Secondary street address (e.g., suite or unit).
    - `city` string — City or locality.
    - `region` string — State, province, or region.
    - `postalCode` string — Postal or ZIP code.
    - `country` string — Country code in ISO 3166-1 alpha-2 format.
    - `regionCustom` string, nullable — Custom region string if region is not standardized.
    - `addressServiceId` string — Optional ID from an external address service.
  - `purchaser` Contact — Contact details used in invoice communication and processing.
    - `id` string — Unique ID for the contact.
    - `email` string — Email address of the contact.
    - `firstName` string — First name of the contact.
    - `lastName` string — Last name of the contact.
    - `fullName` string — Full name of the contact (if applicable).
    - `companyName` string — Company name this contact represents.
    - `phoneNumber` string — Contact's phone number.
    - `website` string — Website URL for the contact or company.
    - `contactType` string — Role of the contact in the invoice (e.g., SHIP-TO, BILL-TO, PAYMENT_FACILITATOR).
    - `contactServiceId` string — Optional reference to an external service’s contact ID.
    - `contactOrganizationId` string — Optional reference to an external service’s organization ID.
  - `purchaserAddress` Address — Address details used for invoice delivery and billing.
    - `id` string — Unique identifier for the address.
    - `addressLine1` string — Primary street address.
    - `addressLine2` string — Secondary street address (e.g., suite or unit).
    - `city` string — City or locality.
    - `region` string — State, province, or region.
    - `postalCode` string — Postal or ZIP code.
    - `country` string — Country code in ISO 3166-1 alpha-2 format.
    - `regionCustom` string, nullable — Custom region string if region is not standardized.
    - `addressServiceId` string — Optional ID from an external address service.
  - `purchaserOrganization` InvoiceOrganization — Organization data associated with a contact.
    - `organizationId` string — Unique ID for the organization.
    - `organizationName` string — Full legal name of the organization.
    - `organizationType` string — Type of business entity.
    - `organizationReference` string — Optional reference code for this organization.
  - `receiver` Contact — Contact details used in invoice communication and processing.
    - `id` string — Unique ID for the contact.
    - `email` string — Email address of the contact.
    - `firstName` string — First name of the contact.
    - `lastName` string — Last name of the contact.
    - `fullName` string — Full name of the contact (if applicable).
    - `companyName` string — Company name this contact represents.
    - `phoneNumber` string — Contact's phone number.
    - `website` string — Website URL for the contact or company.
    - `contactType` string — Role of the contact in the invoice (e.g., SHIP-TO, BILL-TO, PAYMENT_FACILITATOR).
    - `contactServiceId` string — Optional reference to an external service’s contact ID.
    - `contactOrganizationId` string — Optional reference to an external service’s organization ID.
  - `receiverAddress` Address — Address details used for invoice delivery and billing.
    - `id` string — Unique identifier for the address.
    - `addressLine1` string — Primary street address.
    - `addressLine2` string — Secondary street address (e.g., suite or unit).
    - `city` string — City or locality.
    - `region` string — State, province, or region.
    - `postalCode` string — Postal or ZIP code.
    - `country` string — Country code in ISO 3166-1 alpha-2 format.
    - `regionCustom` string, nullable — Custom region string if region is not standardized.
    - `addressServiceId` string — Optional ID from an external address service.
  - `receiverOrganization` InvoiceOrganization — Organization data associated with a contact.
    - `organizationId` string — Unique ID for the organization.
    - `organizationName` string — Full legal name of the organization.
    - `organizationType` string — Type of business entity.
    - `organizationReference` string — Optional reference code for this organization.
  - `shippingTotal` number — Total shipping cost.
  - `subTotal` number — Subtotal amount before tax and discounts.
  - `siteId` string — FastSpring site ID.
  - `taxRate` number — Tax rate applied to the invoice.
  - `taxType` string — Type of tax applied.
  - `totalOrderValue` number — Final order value after taxes and discounts.
  - `totalDiscountValue` number — Total discounts applied to the invoice.
  - `totalTaxValue` number — Total tax applied to the invoice.
  - `version` string — Invoice version number.
  - `notes` string — Invoice notes for internal or customer reference.
  - `paymentInvoiceWebLink` string — Web URL to view the invoice.
  - `paymentInvoicePdfLink` string — Direct download URL for invoice PDF.
  - `paymentInvoiceWebPayLink` string — 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.
  - `paymentCurrencyCode` string — Currency used for invoice payment.
  - `paymentOrderReference` string — Order reference used in payment flow.
  - `paymentDueDate` string, 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.
  - `paymentTotals` InvoiceTotals — Final calculated totals for the invoice.
    - `payableTotalDisplay` string — Formatted string showing final total.
    - `subTotalDisplay` string — Formatted string showing subtotal.
    - `discountTotalDisplay` string — Formatted string showing total discounts.
    - `taxTotalDisplay` string — Formatted string showing total tax.
    - `shippingTotalDisplay` string — Formatted string showing shipping total.
    - `taxExemptionReason` string — Reason for tax exemption if applicable.
    - `payableTotal` number — Final amount due.
    - `subTotal` number — Subtotal amount before taxes and discounts.
    - `discountTotal` number — Total discounts applied.
    - `taxTotal` number — Total tax amount.
    - `feesTotal` number — Total fees added.
    - `shippingTotal` number — Shipping cost.
    - `incomeTotal` number — Income total from this invoice.
    - `payoutFeesTotal` number — Fees deducted before payout.
    - `payoutTaxTotal` number — Taxes deducted before payout.
    - `payoutTotal` number — Final payout total.
  - `tagsJson` string — Stringified JSON metadata tags attached to the invoice at creation. Returned verbatim in the POST response.

## Other responses

- `401` — Authentication credentials are missing or invalid.
- `429` — Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header.
- `500` — Internal server error.

---

[API](https://skmtc.dev/fastspring/apis/fastspring-api-accounts.md) · [All operations](https://skmtc.dev/fastspring/apis/fastspring-api-accounts/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fastspring/fastspring-api-accounts/revisions/ae2f0b97db3e/schema)