Invoice Guide

This page will guide you on how to create and send invoices for collecting payments from your customers.

Invoice Lifecycle

  • Draft: An invoice is created in the draft state. Not visible to the customer.
  • Open: An invoice is marked as open when it is sent to the customer. The customer can view and pay the invoice.
  • Paid: An invoice is marked as paid when the customer pays the invoice.
  • Void: An invoice is marked as void when it is no longer valid. The customer cannot pay the invoice.

Create an invoice

To create an invoice, first finish the following steps:

  1. Create a business account for the business you want to create an invoice for.
  2. Enable payments for the business account using payment onboarding links or SDK Component.
  3. Create a customer counterparty account.

Once you have completed the above steps, you can create an invoice using the below endpoint:

Create a tax type

Before creating a tax-inclusive invoice, you need to define a tax type. This will generate a tax_type_id, which should be included in the invoice request.

Request

POST
api/v1/tax-types
curl --request POST \
"https://payments.your-domain.com/api/v1/tax-types" \
--header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
--data "{
    \"name\": \"Standard Tax\",
    \"percent\": \"18\",
    \"description\": \"Standard Tax\"
}"

The response will include a tax_type_id that you can use in your invoice creation request.

Create an invoice with tax

Request

POST
api/v1/invoices
curl --request POST \
"https://payments.your-domain.com/api/v1/invoices" \
--header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
--data "{
    \"invoice_number\": \"INV-000001\",
    \"invoice_date\": \"1017705600\",
    \"due_date\": \"1594944000\",
    \"customer_business_id\": \"98ed68ce-6964-4c2a-9430-8a849e373c52\",
    \"notes\": \"<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>\",
    \"tax_per_item_enabled\": false,
    \"tax_type_ids\": [\"98ed68ce-6964-4c2a-9430-8a849e373c52\"],
    \"template_name\": \"invoice1\",
    \"items\": [
        {
            \"name\": \"Laptop\",
            \"quantity\": \"2\",
            \"price\": \"10000\",
            \"description\": \"New Laptop with latest features\"
        }
    ]
}"

Create an invoice without tax and discount

Request

POST
api/v1/invoices 
curl --request POST \
"https://payments.your-domain.com/api/v1/invoices" \
--header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
--data "{
    \"invoice_number\": \"INV-000001\",
    \"invoice_date\": \"1017705600\",
    \"due_date\": \"1594944000\",
    \"customer_business_id\": \"98ed68ce-6964-4c2a-9430-8a849e373c52\",
    \"notes\": \"<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>\",
    \"template_name\": \"invoice1\",
    \"items\": [
        {
            \"name\": \"Laptop\",
            \"quantity\": \"2\",
            \"price\": \"10000\",
            \"description\": \"New Laptop with latest features\"
        }
    ]
}"

Create an invoice with fixed discount

Request

POST
api/v1/invoices 
curl --request POST \
"https://payments.your-domain.com/api/v1/invoices" \
--header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
--data "{
    \"invoice_number\": \"INV-000001\",
    \"invoice_date\": \"1017705600\",
    \"due_date\": \"1594944000\",
    \"customer_business_id\": \"98ed68ce-6964-4c2a-9430-8a849e373c52\",
    \"notes\": \"<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>\",
    \"discount_type\": \"fixed\",
    \"discount\": \"1000\",
    \"template_name\": \"invoice1\",
    \"items\": [
        {
            \"name\": \"Laptop\",
            \"quantity\": \"2\",
            \"price\": \"10000\",
            \"description\": \"New Laptop with latest features\"
        }
    ]
}"

Create an invoice with item-level tax

Request

POST
api/v1/invoices
curl --request POST \
"https://payments.your-domain.com/api/v1/invoices" \
--header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
--data "{
    \"invoice_number\": \"INV-000001\",
    \"invoice_date\": \"1017705600\",
    \"due_date\": \"1594944000\",
    \"customer_business_id\": \"98ed68ce-6964-4c2a-9430-8a849e373c52\",
    \"notes\": \"<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>\",
    \"template_name\": \"invoice1\",
    \"tax_per_item_enabled\": true,
    \"items\": [
        {
            \"name\": \"Laptop\",
            \"quantity\": \"2\",
            \"price\": \"10000\",
            \"description\": \"New Laptop with latest features\",
            \"tax_type_ids\": [\"98ed68ce-6964-4c2a-9430-8a849e373c52\"]
        }
    ]
}"

Create an invoice with item-level tax and discount

Request

POST
api/v1/invoices 
curl --request POST \
"https://payments.your-domain.com/api/v1/invoices" \
--header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
--data "{
    \"invoice_number\": \"INV-000001\",
    \"invoice_date\": \"1017705600\",
    \"due_date\": \"1594944000\",
    \"customer_business_id\": \"98ed68ce-6964-4c2a-9430-8a849e373c52\",
    \"notes\": \"<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>\",
    \"template_name\": \"invoice1\",
    \"tax_per_item_enabled\": true,
    \"items\": [
        {
            \"name\": \"Laptop\",
            \"quantity\": \"2\",
            \"price\": \"10000\",
            \"description\": \"New Laptop with latest features\",
            \"discount_type\": \"fixed\",
            \"discount\": \"100\",
            \"tax_type_ids\": [\"98ed68ce-6964-4c2a-9430-8a849e373c52\"]
        }
    ]
}"

You can read more about this endpoint as well as how to update and delete an invoice in the Invoice API Reference.

Send invoice to customer

There are two ways to send an invoice to your customer:

  1. Send an invoice directly from Crater. (Your email credentials should be configured in Crater)
  2. Create an invoice link and send it yourself.
  3. Show the invoice on your app or website using SDK Component.

1. Send an invoice directly from Crater

Request

POST
api/v1/invoices/{id}/send-email
curl --request POST \
"https://payments.your-domain.com/api/v1/invoices/9aae0110-a4d6-4552-99de-4b4d3e3432f8/send-email" \
--header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
--data "{
    \"body\": \"<p>You have received a new invoice from {BUSINESS_NAME}.</p><p>Please view the invoice and approve it within 7 days of receiving this email.</p>\",
    \"subject\": \"You have received a new invoice from {VENDOR_BUSINESS_NAME}\",
    \"reply_to\": \"business_email@example.com\",
    \"to\": \"customer_email@example.com\"
}"

2. Create an invoice link and send it yourself

Request

GET
api/v1/invoices/{invoice_id}/links
curl --request GET \
--get "https://payments.your-domain.com/api/v1/invoices/9aae0110-a4d6-4552-99de-4b4d3e3432f8/links" \
--header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \

Download Invoice PDF

Invoices can be downloaded using the invoice_pdf_url attribute from the create, update, and retrieve endpoints. This attribute provides a direct link to the PDF version of the invoice, making it easy to download and share.

This attribute is returned in the response of the following endpoints:

  1. Create Invoice endpoint.
  2. Update Invoice endpoint.
  3. Retrieve Invoice endpoint.

In each of these endpoints, the response includes a invoice_pdf_url attribute. You can use this URL to download the PDF version of the invoice.

Response

JSON
{
    "invoice_number": "INV-000001",
    "invoice_date": "1017705600",
    "due_date": "1594944000",
    "customer_business_id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "notes": "<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>",
    "template_name": "invoice1",
    "items": [
        {
            "name": "Laptop",
            "quantity": "2",
            "price": "10000",
            "description": "New Laptop with latest features",
            "tax": "100"
        }
    ],
    "invoice_pdf_url": "https://payments.your-domain.com/invoices/INV-000001/download"
}