Invoices
Invoices are bills that need to be paid by your customers. The Invoice API allows you to create, retrieve, update, and delete invoices, including managing line items for products and services being billed.
The Invoice object
Attributes
Unique identifier for the invoice.
The customer who will be billed.
String representing the object's type.
The total amount of the invoice in cents.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
Current status of the invoice. Can be one of: draft, outstanding, due, overdue, paid, written_off, voided.
The collection method for this invoice.
Automatically charge the customer's payment method when the invoice is issued.
Send a payment request to the customer when the invoice is issued.
Number of days before the invoice is due. Default is 0 (due immediately).
Unique number that identifies this invoice. If not provided, will be auto-generated.
An arbitrary string attached to the invoice. Often useful for displaying to customers.
Internal notes for the invoice (not visible to customers).
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
A metadata object consists of key-value pairs that can be attached to Frame object. Use metadata to store structured, additional information about the object for your reference. Learn more about storing information in metadata.
A list of line items that make up the invoice. Each line item represents a product with quantity and price.
Time at which the invoice was created.
Time at which the invoice was last updated.
{
"id": "f131cfbb-7fcf-4c72-8aab-958375a35830",
"object": "invoice",
"invoice_number": "804D5557-0001",
"customer": {
"object": "customer",
"id": "605f1a98-f329-4210-939a-1e06f3b0da8b",
"name": "Jane Doe"
},
"total": 10000,
"currency": "USD",
"status": "draft",
"collection_method": "auto_charge",
"net_terms": 0,
"description": "Monthly subscription",
"memo": "Internal notes",
"livemode": false,
"metadata": {
"order_id": "6735"
},
"line_items": [
{
"object": "line_item",
"id": "li_1234567890",
"quantity": 2,
"product": {
"object": "product",
"id": "prod_1234567890",
"name": "T-shirt",
"price": 2000
}
}
],
"created": 1633046400,
"updated": 1633046400
}
List All Invoices
Retrieves a list of invoices for your merchant account, with optional filtering by customer and status.
Parameters
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
The page offset at which you'd like to resume fetching data.
Filter invoices by customer ID.
Filter invoices by status. Can be one or more of: draft, outstanding, due, overdue, paid, written_off, voided.
Returns
A dictionary with a data property that contains an array of up to limit Invoice objects. Each entry in the array is a separate Invoice object. If no more Invoices are available, the resulting array will be empty.
curl --request GET \
--url https://api.framepayments.com/v1/invoices \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/invoices",
"has_more": false,
"prev": null,
"next": null
},
"data": [
{
"id": "f131cfbb-7fcf-4c72-8aab-958375a35830",
"object": "invoice",
"invoice_number": "804D5557-0001",
"customer": {
"object": "customer",
"id": "605f1a98-f329-4210-939a-1e06f3b0da8b",
"name": "Jane Doe"
},
"total": 240000,
"currency": "USD",
"status": "draft",
"collection_method": "request_payment",
"net_terms": 10,
"description": "description",
"memo": "memo",
"livemode": false,
"created": 1713435744,
"updated": 1713435744,
"metadata": {
"key": "test_key",
"value": "test_value"
},
"line_items": []
}
]
}
Create an Invoice
Creates a new invoice with the specified parameters.
Parameters
The ID of the customer who will be billed.
The collection method for this invoice.
Automatically charge the customer's payment method when the invoice is issued.
Send a payment request to the customer when the invoice is issued.
Number of days before the invoice is due. Default is 0 (due immediately).
Unique number that identifies this invoice. If not provided, will be auto-generated.
An arbitrary string attached to the invoice. Often useful for displaying to customers.
Internal notes for the invoice (not visible to customers).
A metadata object consists of key-value pairs that can be attached to Frame object. Use metadata to store structured, additional information about the object for your reference. Learn more about storing information in metadata.
Array of line items to be added to the invoice.
The ID of the product to be added to the invoice.
The quantity of the product to be added to the invoice.
Returns
Returns the created Invoice object if the request was successful.
curl --request POST \
--url https://api.framepayments.com/v1/invoices \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"customer": "a793a06e-e2d5-4dd0-b495-f1fc0b0a9eb3",
"collection_method": "request_payment",
"metadata": {
"test": "test"
}
}'
{
"id": "a8b4735a-c441-4c6c-88bb-4bd8666c6c89",
"object": "invoice",
"invoice_number": "804D5557-DRAFT",
"customer": {
"object": "customer",
"id": "a793a06e-e2d5-4dd0-b495-f1fc0b0a9eb3",
"name": "Tamala Abshire LLD"
},
"total": 0,
"currency": "USD",
"livemode": false,
"created": 1748357861,
"updated": 1748357861,
"line_items": [],
"collection_method": "request_payment",
"status": "draft",
"metadata": {
"test": "test"
},
"due_date": null,
"description": null,
"memo": null,
"net_terms": 0
}
Update an Invoice
Updates an existing invoice with the specified parameters.
Parameters
The collection method for this invoice.
Automatically charge the customer's payment method when the invoice is issued.
Send a payment request to the customer when the invoice is issued.
Number of days before the invoice is due.
Unique number that identifies this invoice.
An arbitrary string attached to the invoice. Often useful for displaying to customers.
Internal notes for the invoice (not visible to customers).
Set of key-value pairs that you can attach to an invoice.
Array of line items to be added or updated in the invoice.
The ID of the product to be added to the invoice.
The quantity of the product to be added to the invoice.
Returns
Returns the updated Invoice object if the request was successful.
curl --request PATCH \
--url https://api.framepayments.com/v1/invoices/inv_6113c3cb-2304-45e1-9551-fa7fb804418f \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"description": "Updated description",
"line_items": [
{
"product": "prod_1234567890",
"quantity": 2
}
]
}'
{
"id": "f131cfbb-7fcf-4c72-8aab-958375a35830",
"object": "invoice",
"invoice_number": "804D5557-0001",
"customer": {
"object": "customer",
"id": "605f1a98-f329-4210-939a-1e06f3b0da8b",
"name": "Jane Doe"
},
"total": 400000,
"currency": "USD",
"status": "draft",
"collection_method": "request_payment",
"net_terms": 10,
"number": "INV-0001",
"description": "Updated description",
"memo": "memo",
"livemode": false,
"created": 1713435744,
"updated": 1713436000,
"metadata": {
"key": "test_key",
"value": "test_value"
},
"line_items": [
{
"object": "line_item",
"id": "li_1234567890",
"quantity": 2,
"product": {
"object": "product",
"id": "prod_1234567890",
"name": "T-shirt",
"price": 2000
}
}
]
}
Retrieve an Invoice
Retrieves the details of an existing invoice by ID.
Parameters
No parameters.
Returns
Returns an Invoice object if a valid ID was provided.
curl --request GET \
--url https://api.framepayments.com/v1/invoices/inv_6113c3cb-2304-45e1-9551-fa7fb804418f \
--header 'Authorization: Bearer API_KEY'
{
"id": "f131cfbb-7fcf-4c72-8aab-958375a35830",
"object": "invoice",
"invoice_number": "804D5557-0001",
"customer": {
"object": "customer",
"id": "605f1a98-f329-4210-939a-1e06f3b0da8b",
"name": "Jane Doe"
},
"total": 240000,
"currency": "USD",
"status": "draft",
"collection_method": "request_payment",
"net_terms": 10,
"number": "INV-0001",
"description": "description",
"memo": "memo",
"livemode": false,
"created": 1713435744,
"updated": 1713435744,
"metadata": {
"key": "test_key",
"value": "test_value"
},
"line_items": []
}
Delete an Invoice
Deletes a draft invoice. Only invoices in draft status can be deleted.
Parameters
No parameters.
Returns
Returns a confirmation that the invoice has been deleted.
curl --request DELETE \
--url https://api.framepayments.com/v1/invoices/inv_6113c3cb-2304-45e1-9551-fa7fb804418f \
--header 'Authorization: Bearer API_KEY'
{
"object": "invoice",
"deleted": true
}
Issue an Invoice
Issues a draft invoice to the customer, changing its status from draft to open.
Parameters
No parameters.
Returns
Returns the Invoice object with updated status if the request was successful.
curl --request POST \
--url https://api.framepayments.com/v1/invoices/inv_6113c3cb-2304-45e1-9551-fa7fb804418f/issue \
--header 'Authorization: Bearer API_KEY'
{
"id": "f131cfbb-7fcf-4c72-8aab-958375a35830",
"object": "invoice",
"invoice_number": "804D5557-0001",
"customer": {
"object": "customer",
"id": "605f1a98-f329-4210-939a-1e06f3b0da8b",
"name": "Jane Doe"
},
"total": 400000,
"currency": "USD",
"status": "open",
"collection_method": "request_payment",
"net_terms": 10,
"number": "INV-0001",
"description": "Updated description",
"memo": "memo",
"livemode": false,
"created": 1713435744,
"updated": 1713436200,
"metadata": {
"key": "test_key",
"value": "test_value"
},
"line_items": []
}