Create an invoice

Discover how to create an invoice. You can create an invoice without coding via Speed web application or programmatically via invoice APIs.

Create invoices via API

Create an invoice using the /invoices endpoint and basic details such as:

name (mandatory)
email (mandatory)
invoice line items (mandatory)
Currency (mandatory)
description (optional) etc.
Make a POST /invoices request specifying the following mandatory parameters.

As explained below, there are two options through which you can create an Invoice,

Option 1:

You can use the below request,

To create a new customer by providing
1. Your customer’s name
2. His/her email address
You can then provide one/multiple invoice line items having type,
1. As “line_item” i.e., using the existing price created in Speed. Click here to know more about how to create prices in Speed.
2. As “custom_line_item” i.e., by providing new price details runtime (i.e. item name and unit amount).
3. You can also provide line_item and custom_line_item together.
Define your preferred base currency (fiat or SATS/BTC) to create an invoice. A three-lettered ISO-compliant currency name must be used.

IMP: All the price_id attached, must be of same currency define above.

{
    "customer":{
        "name":"Test",
        "email":"[email protected]",
      	"currency":"USD",
      	"billing": {
            "address": {
                "line1": "ABC Society",
                "line2": "PQR Colony",
                "city": "New York"
            }
    },
     		"shipping": {
            "address": {
                "line1": "ABC lane",
                "city": "Vegas",
            }
    },
    "invoice_line_items":[
        {
            "name":"One Time Item",
            "unit_amount":10,
            "quantity":1,
            "type":"custom_line_item"
        },
				{
            "price_id":"price_lkxryzovIyk6Jn4p",
            "quantity":2,
            "type":"line_item"
        }
    ]
    "currency":"USD"
}

Option 2:

You can use the below request,

Create a customer in Speed and attached that customer’s id in “customer_id” attribute. Click here to know more about how to create customers in Speed.
You can then provide one/multiple invoice line items having type,
1. As “line_item” i.e., using the existing price created in Speed. Click here to know more about how to create prices in Speed.
2. As “custom_line_item” i.e., by providing new price details runtime (i.e. item name and amount)
3. You can also provide line_item and custom_line_item together.
Define your preferred base currency (fiat or SATS/BTC) to create an invoice. A three-lettered ISO-compliant currency name must be used.
IMP: All the price_id attached, must be of same currency define above.

{
    "customer_id":"cus_ll0msrg9C39Ss0Gm",
    "invoice_line_items":[
				{
            "name":"One Time Item",
            "unit_amount":0.1,
            "quantity":1,
            "type":"custom_line_item"
        },
        {
            "price_id":"price_lkxryzovIyk6Jn4p",
            "quantity":"2",
            "type":"line_item"
        }
    ],
    "currency":"USD"
}

Request parameters

Provide the basic information outlined in the table below:

Parameter	Sub-parameter	Required	Type	Description
Customer	name	✅	String	You can use this parameter to add a name of your customer. Required if Customer ID not given.
	email	✅	String	You can use this parameter to provide an email of the customer. Required if Customer ID not given.
	billing		String	In this parameter you must specify the address associated with the customer's billing information. This parameter accepts a structured format, including street address, city, state/province and country.
	shipping		String	The "shipping" parameter allows you to specify the destination address for shipping purposes. This parameter should be populated with the relevant shipping details, including the recipient's name, street address, city, state/province, and country.
	phone		String	Customer’s phone number (including extension).
	calling_code		String	Two letter country code (ISO 3166-1 alpha-2).
Customer ID	customer_id	✅	String	You can use this parameter to specify the ID of the customer for which the invoice is to be created. Note: If you've included a customer_id, there's no requirement to furnish customer details, and conversely. However, it's essential to indicate at least one of these options.
Invoice Line Items	invoice_line_items	✅	List	This parameter contains a list of items for the invoice. These items can be of 2 types: 1. line_item You can use this type to create the invoice for an existing price. Price ID and quantity are mandatory fields. 2. custom_line_item You can use this type to apply a new price to the invoice. Please keep in mind that no new price id will be created. Name, unit amount, quantity are mandatory fields. You can add multiple invoice line items combining of both the types in the same invoice.
currency		✅	String	In this parameter you must specify the currency to create an invoice.
invoice_emails_cc			String	In this parameter you can effortlessly include additional email addresses in the CC field of invoice-related emails keeping multiple stakeholders informed about the invoice details and updates. You can add upto five email addresses.
memo			String	You can use this parameter for including additional information or notes related to the invoice. This description helps provide context, clarification, or specific details about the invoice transaction.
footer			String	You can use this parameter to provide additional information, disclaimers, or custom messages that appear at the bottom of the invoice document. It serves as a space for including any relevant context, terms and conditions, or personalized messages for the recipient.
metadata			Object	You can use this object to store additional information in key-value pairs about the payment link object in a structured format.

💡
Any of "Customer" or "Customer ID" must be provided in the request parameters.

More information can be found in our API reference.

Response parameters

{
    "id": "in_ll0ncse9lGQw5X3e",
    "object": "invoices",
    "currency": "USD",
    "customer_id": "cus_ll0msrg9C39Ss0Gm",
    "description": "description",
    "hosted_invoice_url": null,
    "status": "DRAFT",
    "invoice_amount": 100,
    "invoice_amount_paid": 0,
    "invoice_due_date": null,
    "invoice_pdf": null,
    "invoice_number": "INV-DRAFT",
    "invoice_emails_cc": [],
    "statement_descriptor": null,
    "footer": null,
    "status_transition": {
        "finalized_at": null,
        "paid_at": null,
        "uncollectible_at": null,
        "voided_at": null
    },
    "invoice_line_items": [
        {
            "id": "il_ll0ncsegotIKOwu7",
            "created": 1691399102913,
            "modified": 1691399102913,
            "name": "Test Name",
            "currency": null,
            "price_id": "price_lkxryzovIyk6Jn4p",
            "quantity": 2,
            "unit_amount": 50,
            "row_total_amount": 100,
            "product_id": "prod_lkxryzouNzFU81Bh",
            "product_images": [],
            "type": "line_item"
        }
    ],
    "customer": {
        "name": "Test",
        "email": "[email protected]",
        "currency": null,
        "billing": {
            "address": {
                "line1": "4835",
                "line2": "Lake Forest Drive",
                "city": "Monsey",
                "state": null,
                "country": null,
                "zipcode": null
            },
            "email": "[email protected]",
            "email_cc": [
                "[email protected],[email protected]"
            ]
        },
        "shipping": {
            "address": {
                "line1": "4835",
                "line2": "Lake Forest Drive",
                "city": "Monsey",
                "state": null,
                "country": "INR",
                "zipcode": null
            },
            "name": null,
            "email": null,
            "phone": "12344533",
            "calling_code": "+1"
        },
        "phone": null,
        "calling_code": null
    },
    "created": 1691399102904,
    "modified": 1691399102904
}

Attributes

id string
Unique identifier for the object.

object string
The type of the object indicates to which entity this response belongs.

currency string
This represents the currency of the invoice.

customer_id string
This attribute represents the ID of the customer to which the invoice belongs.

description string
This attribute represents additional information about the invoice.

hosted_invoice_url string
This attribute represents the URL for the hosted invoice page, which allows customers to view and pay an invoice. If the invoice has not been finalized yet, this will be null.

status string
This attribute indicates the status of the invoice. The invoice is created with draft status by default. Invoice has other statuses such as open, paid and void.

invoice_amount decimal
This attribute represents the amount of the invoice.

invoice_amount_paid decimal
This attribute represents the amount that has been paid for the invoice.

invoice_due_date timestamp
This attribute represents the date when the invoice is due for payment. It is null if no due date is set in the invoice settings.

invoice_pdf string
The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.

invoice_number string
This attribute has default value “INV-DRAFT”. It is formed by appending invoice prefix with the sequence number.

invoice_emails_cc string
This attribute includes additional email addresses in the CC field of invoice-related emails keeping multiple stakeholders informed about the invoice details and updates. You can add upto five email addresses.

footer string
This attribute provides additional information, disclaimers, or custom messages that appear at the bottom of the invoice document.

memo string
This attribute includes additional information or notes related to the invoice. This description helps provide context, clarification, or specific details about the invoice transaction.

invoice_line_items list
The line items that make up the invoice.

line_item
This type is used to create the invoice for an existing price. Price ID and quantity are mandatory fields here.
custom_line_item
This type is used to apply a new price to the invoice. Please keep in mind that no new price id will be created. Name, unit amount, quantity are mandatory fields here.

customer object
The details of the customer to whom the invoice belongs.

name
This attribute includes name of the customer. Required if Customer ID not given.
email
You can use this parameter to provide an email of the customer. Required if Customer ID not given.
billing
This attribute includes the address associated with the customer's billing information. This field accepts a structured format, including street address, city, state/province and country.
shipping
This attribute includes the destination address for shipping purposes. This filed should be populated with the relevant shipping details, including the recipient's name, street address, city, state/province, and country.
phone
Customer’s phone number (including extension).
calling_code
Two letter country code (ISO 3166-1 alpha-2).

created timestamp
Time at which the invoice was created.

modified timestamp
Time at which the last modification was made.