Invoices

Create and manage invoices. Invoices are statements of amounts owed, generated automatically for subscriptions or created manually for one-time charges.

The Invoice object

Attributes
idstring

Unique identifier for the invoice

objectstring

Object type identifier. Always invoice.

invoice_numberstring

Human-readable invoice number

totalinteger

Total amount in cents

currencystring

Three-letter ISO currency code

statusstring

Current status. One of draft, open, paid, void, or uncollectible.

collection_methodstring

How payment is collected. One of charge_automatically or request_payment.

net_termsinteger

Payment terms in days

due_datenullable string

Invoice due date in ISO 8601 format

descriptionnullable string

Optional invoice description

memonullable string

Optional memo shown on the invoice

customernullable object

The customer this invoice is for, if any

accountnullable object

The account this invoice is for, if any

line_itemsarray

Line items on this invoice

metadataobject

Set of key-value pairs for your own reference

livemodeboolean

true if live mode, false if test mode

createdinteger

Unix timestamp of creation

updatedinteger

Unix timestamp of last update

THE INVOICE OBJECT
{
  "id": "f7g8h9i0-4567-8901-defa-2b3c4d5e6f7a",
  "object": "invoice",
  "invoice_number": "INV-0042",
  "total": 5000,
  "currency": "usd",
  "status": "open",
  "collection_method": "charge_automatically",
  "net_terms": 30,
  "due_date": "2024-08-14",
  "description": null,
  "memo": null,
  "customer": {},
  "account": {},
  "line_items": [
    {
      "id": "h9i0j1k2-6789-0123-fabc-4d5e6f7a8b9c",
      "object": "invoice_line_item",
      "description": "Platform Plus — Jul 2024",
      "quantity": 1,
      "unit_amount_cents": 5000,
      "unit_amount_currency": "USD",
      "created": 1721010605,
      "updated": 1721010605
    }
  ],
  "metadata": {},
  "livemode": false,
  "created": 1721010605,
  "updated": 1721010605
}

List invoice line items

Retrieves a list of line items for a specific invoice. Line items represent individual products or services being billed on an invoice.

Path parameters
invoice_idstringrequired

Invoice ID

Returns

A dictionary with a data property that contains an array of Line Item objects

GET/v1/invoices/{invoice_id}/line_items
curl --request GET \
  --url https://api.framepayments.com/v1/invoices/a70cd72f-e74a-40f2-96a2-3f60714aac4a/line_items \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "data": [
    {
      "id": "32f7e4eb-4349-4e26-bc6e-d44af5a40787",
      "description": "Invoice line item description",
      "quantity": 1,
      "unit_amount_cents": 1000,
      "unit_amount_currency": "USD",
      "object": "invoice_line_item",
      "created": 1781115877,
      "updated": 1781115877
    }
  ]
}

Create an invoice line item

Creates a new line item for a specific invoice. Line items can only be added when the invoice is in draft state.

Path parameters
invoice_idstringrequired

Invoice ID

Query parameters
productstringrequired

The ID of the product to be added to the invoice

quantityintegerrequired

The quantity of the product to be added to the invoice. Must be greater than 0.

Returns

Returns the created Line Item object if the request was successful

POST/v1/invoices/{invoice_id}/line_items
curl --request POST \
  --url https://api.framepayments.com/v1/invoices/a70cd72f-e74a-40f2-96a2-3f60714aac4a/line_items \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "7e18e08f-3995-440c-be1e-1b15c5458534",
  "description": "Gorgeous Aluminum Computer",
  "quantity": 2,
  "unit_amount_cents": 10000,
  "unit_amount_currency": "USD",
  "object": "invoice_line_item",
  "created": 1781115877,
  "updated": 1781115877
}

Retrieve an invoice line item

Retrieves the details of an existing line item. Returns a Line Item object if a valid ID was provided.

Path parameters
invoice_idstringrequired

Invoice ID

idstringrequired

Line item ID

Returns

Returns a Line Item object if a valid ID was provided

GET/v1/invoices/{invoice_id}/line_items/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/invoices/a70cd72f-e74a-40f2-96a2-3f60714aac4a/line_items/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "63bdbbd8-fefd-4031-94ab-e109a06f8d43",
  "description": "Invoice line item description",
  "quantity": 1,
  "unit_amount_cents": 1000,
  "unit_amount_currency": "USD",
  "object": "invoice_line_item",
  "created": 1781115877,
  "updated": 1781115877
}

Update an invoice line item

Updates an existing line item for a specific invoice. Line items can only be edited when the invoice is in draft state.

Path parameters
invoice_idstringrequired

Invoice ID

idstringrequired

Line item ID

Query parameters
quantityintegeroptional

The new quantity for the line item. Must be greater than 0.

Returns

Returns the updated Line Item object if the request was successful

PATCH/v1/invoices/{invoice_id}/line_items/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/invoices/a70cd72f-e74a-40f2-96a2-3f60714aac4a/line_items/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "c59dbec5-b781-4ae5-8cee-df7352d928a4",
  "description": "Invoice line item description",
  "quantity": 5,
  "unit_amount_cents": 1000,
  "unit_amount_currency": "USD",
  "object": "invoice_line_item",
  "created": 1781115878,
  "updated": 1781115878
}

Delete an invoice line item

Deletes a line item from an invoice. Line items cannot be deleted if the invoice is paid.

Path parameters
invoice_idstringrequired

Invoice ID

idstringrequired

Line item ID

Returns

Returns a confirmation that the line item has been deleted

DELETE/v1/invoices/{invoice_id}/line_items/{id}
curl --request DELETE \
  --url https://api.framepayments.com/v1/invoices/a70cd72f-e74a-40f2-96a2-3f60714aac4a/line_items/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "object": "invoice_line_item",
  "deleted": true
}

List invoices

Retrieves a list of invoices for your merchant account, with optional filtering by customer and status. Returns a dictionary with a data property that contains an array of Invoice objects. If no more invoices are available, the resulting array will be empty.

Query parameters
pageintegeroptional

The page offset at which you'd like to resume fetching data.

per_pageintegeroptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

customerstringoptional

Filter invoices by customer ID.

statusenumoptional

Filter invoices by status. One of draft, outstanding, due, overdue, paid, written_off, or voided.

accountstringoptional

Filter by account ID.

Returns

A dictionary with a data property containing an array of Invoice objects.

GET/v1/invoices
curl --request GET \
  --url https://api.framepayments.com/v1/invoices \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/invoices?status=",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "b34432cd-f128-4ccc-b95f-67f9f17ce68e",
      "invoice_number": "17",
      "collection_method": "request_payment",
      "status": "draft",
      "due_date": null,
      "description": "Invoice description",
      "memo": null,
      "net_terms": 0,
      "object": "invoice",
      "total": 1000,
      "currency": "USD",
      "livemode": false,
      "created": 1781115878,
      "updated": 1781115878,
      "metadata": {},
      "customer": {
        "id": "2702d7c6-3ecd-4184-8460-dc6ae63a2df7",
        "name": "Msgr. Terrilyn Collins",
        "email": "customer@frame.com",
        "description": "quia",
        "status": "active",
        "date_of_birth": null,
        "phone": "+13107484186",
        "payment_methods": [],
        "billing_address": null,
        "shipping_address": null,
        "object": "customer",
        "created": 1781115878,
        "updated": 1781115878,
        "livemode": false,
        "metadata": {}
      },
      "line_items": []
    },
    {
      "id": "9e22226e-c39e-4732-bcbc-f7c13cdd2bcd",
      "invoice_number": "16",
      "collection_method": "request_payment",
      "status": "draft",
      "due_date": null,
      "description": "Invoice description",
      "memo": null,
      "net_terms": 0,
      "object": "invoice",
      "total": 1000,
      "currency": "USD",
      "livemode": false,
      "created": 1781115878,
      "updated": 1781115878,
      "metadata": {},
      "customer": {
        "id": "2702d7c6-3ecd-4184-8460-dc6ae63a2df7",
        "name": "Msgr. Terrilyn Collins",
        "email": "customer@frame.com",
        "description": "quia",
        "status": "active",
        "date_of_birth": null,
        "phone": "+13107484186",
        "payment_methods": [],
        "billing_address": null,
        "shipping_address": null,
        "object": "customer",
        "created": 1781115878,
        "updated": 1781115878,
        "livemode": false,
        "metadata": {}
      },
      "line_items": []
    },
    {
      "id": "ec93efc4-1a91-4518-a4c7-9c9b227e893a",
      "invoice_number": "15",
      "collection_method": "request_payment",
      "status": "draft",
      "due_date": null,
      "description": "Invoice description",
      "memo": null,
      "net_terms": 0,
      "object": "invoice",
      "total": 1000,
      "currency": "USD",
      "livemode": false,
      "created": 1781115878,
      "updated": 1781115878,
      "metadata": {},
      "customer": {
        "id": "2702d7c6-3ecd-4184-8460-dc6ae63a2df7",
        "name": "Msgr. Terrilyn Collins",
        "email": "customer@frame.com",
        "description": "quia",
        "status": "active",
        "date_of_birth": null,
        "phone": "+13107484186",
        "payment_methods": [],
        "billing_address": null,
        "shipping_address": null,
        "object": "customer",
        "created": 1781115878,
        "updated": 1781115878,
        "livemode": false,
        "metadata": {}
      },
      "line_items": []
    }
  ]
}

Create invoice

Creates a new invoice with the specified parameters. Returns the created Invoice object if the request was successful.

Query parameters
customerstringoptional

The ID of the customer who will be billed.

accountstringoptional

Account ID (mutually exclusive with customer).

collection_methodenumrequired

The collection method for this invoice. auto_charge automatically charges the customer's payment method when the invoice is issued. request_payment sends a payment request to the customer when the invoice is issued.

due_datestringoptional

Invoice due date.

descriptionstringoptional

An arbitrary string attached to the invoice. Often useful for displaying to customers.

currencystringoptional

Three-letter ISO currency code, in lowercase. Must be a supported currency.

net_termsintegeroptional

Number of days before the invoice is due. Default is 0 (due immediately).

memostringoptional

Internal notes for the invoice (not visible to customers).

Returns

Returns the created Invoice object.

POST/v1/invoices
curl --request POST \
  --url https://api.framepayments.com/v1/invoices \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "cb021764-2ace-4260-b8ff-62a2d27f2383",
  "invoice_number": "FC4D3BFE-DRAFT",
  "collection_method": "request_payment",
  "status": "draft",
  "due_date": null,
  "description": "Test invoice",
  "memo": null,
  "net_terms": 0,
  "object": "invoice",
  "total": 0,
  "currency": "USD",
  "livemode": false,
  "created": 1781115878,
  "updated": 1781115878,
  "metadata": {},
  "customer": {
    "id": "2d2da850-1863-4f1d-b38b-42d0b95641ec",
    "name": "Pres. Agustin Strosin",
    "email": "customer@frame.com",
    "description": "et",
    "status": "active",
    "date_of_birth": null,
    "phone": "+13107484186",
    "payment_methods": [],
    "billing_address": null,
    "shipping_address": null,
    "object": "customer",
    "created": 1781115878,
    "updated": 1781115878,
    "livemode": false,
    "metadata": {}
  },
  "line_items": []
}

Get invoice

Retrieves the details of an existing invoice by ID. Returns an Invoice object if a valid ID was provided.

Path parameters
idstringrequired

The ID of the invoice to retrieve.

Returns

Returns the Invoice object.

GET/v1/invoices/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/invoices/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "7af3b830-a5cd-4442-af4f-3296502291fe",
  "invoice_number": "18",
  "collection_method": "request_payment",
  "status": "draft",
  "due_date": null,
  "description": "Invoice description",
  "memo": null,
  "net_terms": 0,
  "object": "invoice",
  "total": 1000,
  "currency": "USD",
  "livemode": false,
  "created": 1781115878,
  "updated": 1781115878,
  "metadata": {},
  "customer": {
    "id": "780ccbb5-2da5-4724-ad1c-9d66d0a60412",
    "name": "Rep. Felisha Wiza",
    "email": "customer@frame.com",
    "description": "laudantium",
    "status": "active",
    "date_of_birth": null,
    "phone": "+13107484186",
    "payment_methods": [],
    "billing_address": null,
    "shipping_address": null,
    "object": "customer",
    "created": 1781115878,
    "updated": 1781115878,
    "livemode": false,
    "metadata": {}
  },
  "line_items": []
}

Update invoice

Updates an existing invoice with the specified parameters. Returns the updated Invoice object if the request was successful.

Path parameters
idstringrequired

The ID of the invoice to update.

Query parameters
collection_methodenumoptional

The collection method for this invoice. auto_charge automatically charges the customer's payment method when the invoice is issued. request_payment sends a payment request to the customer when the invoice is issued.

due_datestringoptional

Invoice due date.

descriptionstringoptional

An arbitrary string attached to the invoice. Often useful for displaying to customers.

net_termsintegeroptional

Number of days before the invoice is due.

memostringoptional

Internal notes for the invoice (not visible to customers).

auto_advancebooleanoptional

Whether to automatically advance the invoice.

Returns

Returns the updated Invoice object.

PATCH/v1/invoices/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/invoices/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "669bd87e-c8d6-4196-ad64-53e49dcad5ba",
  "invoice_number": "19",
  "collection_method": "request_payment",
  "status": "draft",
  "due_date": null,
  "description": "New description",
  "memo": null,
  "net_terms": 0,
  "object": "invoice",
  "total": 1000,
  "currency": "USD",
  "livemode": false,
  "created": 1781115879,
  "updated": 1781115879,
  "metadata": {},
  "customer": {
    "id": "8182f67b-7797-46cb-b40e-f64f6c87dd85",
    "name": "Gov. Twanda Gottlieb",
    "email": "customer@frame.com",
    "description": "nesciunt",
    "status": "active",
    "date_of_birth": null,
    "phone": "+13107484186",
    "payment_methods": [],
    "billing_address": null,
    "shipping_address": null,
    "object": "customer",
    "created": 1781115879,
    "updated": 1781115879,
    "livemode": false,
    "metadata": {}
  },
  "line_items": []
}

Issue invoice

Issues a draft invoice to the customer, changing its status from draft to open. Returns the Invoice object with updated status if the request was successful.

Path parameters
idstringrequired

The ID of the draft invoice to issue.

Returns

Returns the Invoice object with updated status.

POST/v1/invoices/{id}/issue
curl --request POST \
  --url https://api.framepayments.com/v1/invoices/a70cd72f-e74a-40f2-96a2-3f60714aac4a/issue \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "8af0a6f5-ab43-49d4-990d-9f2b1c82c371",
  "invoice_number": "20",
  "collection_method": "request_payment",
  "status": "due",
  "due_date": "2026-06-10T18:24:39.484Z",
  "description": "Invoice description",
  "memo": null,
  "net_terms": 0,
  "object": "invoice",
  "total": 1000,
  "currency": "USD",
  "livemode": false,
  "created": 1781115879,
  "updated": 1781115879,
  "metadata": {},
  "customer": {
    "id": "3de7ab0d-ac59-4d2f-bdfb-46b185d29387",
    "name": "Denyse O'Connell",
    "email": "customer@frame.com",
    "description": "earum",
    "status": "active",
    "date_of_birth": null,
    "phone": "+13107484186",
    "payment_methods": [],
    "billing_address": null,
    "shipping_address": null,
    "object": "customer",
    "created": 1781115879,
    "updated": 1781115879,
    "livemode": false,
    "metadata": {}
  },
  "line_items": []
}