Invoice API Reference

This documentation provides detailed information, examples, and best practices for effectively utilizing the Invoice model. Discover how to create, retrieve, update, and manage invoices effortlessly. Explore the powerful API endpoints and data structures available, empowering you to seamlessly handle invoices within your system. Enhance your invoicing workflow and streamline financial processes by leveraging our Invoice API.

The Invoice model

Invoices are documents that outline the costs of products or services provided by a business. They include details like item descriptions, quantities, prices, and total amounts. Invoices are crucial for transparent transactions, helping businesses and customers keep track of financial dealings.

Properties

Name
id
Type
string
Field Type
Description
Unique identifier for the invoice.
Name
invoice_date
Type
timestamp
Field Type
Description
Date of the invoice.
Name
due_date
Type
timestamp
Field Type
Description
Due Date.
Name
invoice_number
Type
string
Field Type
Description
Invoice Number.
Name
sequence_number
Type
integer
Field Type
Description
Sequence number.
Name
status
Type
string
Field Type
Description
Status of the invoice.
Name
notes
Type
string
Field Type
Description
Invoice Notes.
Name
discount
Type
float
Field Type
Description
Discount value.
Name
discount_type
Type
string
Field Type
Description
Type of discount: fixed or percentage.
Name
discount_val
Type
integer
Field Type
Description
Discount value in cents.
Name
tax
Type
integer
Field Type
Description
Tax in cents.
Name
sub_total
Type
integer
Field Type
Description
Subtotal in cents.
Name
total
Type
integer
Field Type
Description
Total in cents.
Name
template_name
Type
string
Field Type
Description
Name of the template to be used for the invoice PDF.
Name
customer_business_id
Type
string
Field Type
Description
Customer Business ID.
Name
invoice_pdf_url
Type
string
Field Type
Description
URL of the invoice PDF.
Name
attachments
Type
array
Field Type
Description
Array of attachments.
Name
reject_reason
Type
string
Field Type
Description
Reason for rejection.
Name
items
Type
object
Field Type
Description
Invoice items object
Name
customer
Type
object
Field Type
Description
Customer object.
Name
tax_per_item_enabled
Type
boolean
Field Type
Description
Tax per item enabled.
Name
discount_per_item_enabled
Type
boolean
Field Type
Description
Discount per item enabled.
Name
creator_id
Type
string
Field Type
Description
ID of the user who created the invoice.
Name
billing_address
Type
object
Field Type
Description
Billing address of the estimate.
Name
shipping_address
Type
object
Field Type
Description
Shipping address of the estimate.
Name
created_at
Type
timestamp
Field Type
Description
Date of creation.
Name
paid_status
Type
string
Field Type
Description
Paid status of the invoice.
Name
due_amount
Type
integer
Field Type
Description
Due amount in cents.
Name
sent_at
Type
timestamp
Field Type
Description
Date of sending.
Name
viewed_at
Type
timestamp
Field Type
Description
Date of viewing.
Name
overdue_at
Type
timestamp
Field Type
Description
Date of overdue.
Name
vendor_business_id
Type
string
Field Type
Description
Vendor Business ID.
Name
payee_loan_status
Type
string
Field Type
Description
Payee loan status.
Name
payor_loan_status
Type
string
Field Type
Description
Payor loan status.
Name
vendor
Type
object
Field Type
Description
Vendor object.

GETapi/v1/invoices/templates

List all invoice templates

This endpoint returns a list invoice templates.

Request

GET

api/v1/invoices/templates

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

Response

{
  "invoiceTemplates": [
    {
      "name": "invoice1",
      "path": "/templates/invoice1.png"
    },
    {
      "name": "invoice2",
      "path": "/templates/invoice2.png"
    },
    {
      "name": "invoice3",
      "path": "/templates/invoice3.png"
    }
  ]
}

GETapi/v1/invoices

List all invoices

This endpoint allows you to retrieve a paginated list of all your invoices.

Query Parameters

Name
limit
Type
integer
Field Type
optional
Description
Limit the number of invoices to be returned. (default is 10)
Name
page
Type
integer
Field Type
optional
Description
Page number for pagination. (default is 1)
Name
status
Type
string
Field Type
optional
Description
Filter records by status.
Name
type
Type
string
Field Type
optional
Description
1. incoming: Fetch invoices where the current business is the customer.
2. outgoing: Fetch invoices where the current business is the vendor.
3. All Invoices (if type is not provided): Fetch all invoices involving the current business as either a vendor or customer. If the business can act as both, include both types of invoices. If the business is only a customer, fetch customer invoices. If the business is only a vendor, fetch vendor invoices.
Name
customer_business_id
Type
string
Field Type
optional
Description
Filter by customer_business_id (Only fetch invoices of a given customer of this business)
Name
invoice_number
Type
string
Field Type
optional
Description
Filter records by invoice_number .
Name
from_date
Type
timestamp
Field Type
optional
Description
Filter records by from_date.
Name
to_date
Type
timestamp
Field Type
optional
Description
Filter records by to_date.

Request

GET

api/v1/invoices

curl --request GET \
  --get "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" \

Response

{
  "data": [
    {
      "id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
      "estimate_id": "99745a4e-7a6b-4be4-a87e-2826e457ae06",
      "invoice_number": "INV-000001",
      "invoice_date": 1017705600,
      "due_date": 1594944000,
      "customer_business_id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
      "template_name": "invoice1",
      "items" : [
        {
          "id": "99745a4e-7d35-4766-974d-1a225e2258ac",
          "name": "Apple Macbook",
          "description": "Light and powerful laptop",
          "discount_type": "fixed",
          "quantity": 2,
          "unit_name": "box",
          "discount": 0,
          "discount_val": 0,
          "price": 10000,
          "tax": 0,
          "total": 20000,
          "item_id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
          "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
          "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
        }
      ],
      "sequence_number": 1,
      "status": "DRAFT",
      "notes": "<p>The total amount of the attached estimate EST-000001 is $190.00</p>",
      "notes_raw": "<p>The total amount of the attached estimate {ESTIMATE_NUMBER} is {TOTAL_AMOUNT}</p>",
      "discount": 5,
      "discount_type": "percentage",
      "discount_val": 1000,
      "tax": 0,
      "sub_total": 20000,
      "sent_at": null,
      "viewed_at": null,
      "approved_at": null,
      "overdue_at": null,
      "invoice_pdf_url": "https://payments.your-domain.com/invoices/pdf/9aae0110-a4d6-4552-99de-4b4d3e3432f8",
      "attachments": [],
      "customer": {},
      "tax_per_item_enabled": false,
      "discount_per_item_enabled": false,
      "created_at": 1667663245,
      "billing_address": {},
      "shipping_address": {},
      "paid_status": "UNPAID",
      "total": 19000,
      "due_amount": 19000,
      "sent_to_oatfi": null,
      "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
      "scheduled_date": null,
      "payee_loan_status": "DRAFT",
      "payor_loan_status": "DRAFT",
      "allowed_paid_invoice_states": [
          "PARTIALLY_PAID",
          "PAID"
      ],
      "integrations": [],
      "recurring_auto_pay_authorized": false
    }, {...}
  ]
}

POSTapi/v1/invoices

Create an invoice

This endpoint allows you to create an invoice.

Body Parameters

Name
invoice_number
Type
string
Field Type
required
Description
Invoice Number.
Name
invoice_date
Type
timestamp
Field Type
required
Description
Date of the invoice.
Name
due_date
Type
timestamp
Field Type
required
Description
Due Date.
Name
customer_business_id
Type
string
Field Type
required
Description
Customer Business ID.
Name
template_name
Type
string
Field Type
required
Description
Name of the template to be used for the invoice PDF.
Name
discount
Type
float
Field Type
optional
Description
Discount value. Pass percentage of the discount or the amount if the discount is fixed in cents. Example: 10 (percentage) or 1000(fixed).
Name
discount_type
Type
string
Field Type
optional
Description
Type of discount: fixed or percentage.
Name
tax_type_ids
Type
array
Field Type
optional
Description
Array of Tax type IDs.
Name
notes
Type
string
Field Type
optional
Description
Invoice Notes.
Name
items[].name
Type
string
Field Type
required
Description
Name of Item.
Name
items[].quantity
Type
integer
Field Type
required
Description
Item Quantity.
Name
items[].price
Type
integer
Field Type
required
Description
Item Price in cents.
Name
items[].description
Type
string
Field Type
optional
Description
Item Description.
Name
items[].item_id
Type
string
Field Type
optional
Description
Item ID.
Name
items[].unit_name
Type
string
Field Type
optional
Description
Item Unit Name.
Name
items[].discount
Type
float
Field Type
optional
Description
Actual discount value that appears on the PDF. Pass percentage of the discount or the amount if the discount is fixed.
Name
items[].discount_type
Type
string
Field Type
optional
Description
Type of discount: fixed or percentage.
Name
items[].tax_type_ids
Type
array
Field Type
optional
Description
Array of Tax type IDs.

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\",
    \"discount_type\": \"percentage\",
    \"discount\": \"5\",
    \"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\",
        \"item_id\": \"9911d6af-02ee-40dd-b8da-95df7301bd18\",
        \"unit_name\": \"box\",
        \"discount\": \"0\",
        \"discount_type\": \"fixed\"
      }
    ]
  }"

Response

{
  "data": {
    "id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
    "estimate_id": null,
    "invoice_number" : "INV-000001",
    "invoice_date" : 1017705600,
    "due_date" : 1594944000,
    "customer_business_id" : "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "template_name" : "invoice1",
    "items": [
      {
        "id": "9974c9fc-5dfc-4262-81b8-f42e3275119b",
        "name": "Laptop",
        "description": "New Laptop with latest features",
        "discount_type": null,
        "price": 10000,
        "quantity": 2,
        "unit_name": null,
        "discount": 0,
        "discount_val": 0,
        "tax": 0,
        "total": 20000,
        "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
        "item_id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
        "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
      }
    ],
    "sequence_number" : 1,
    "status" : "DRAFT",
    "notes" : "<p>The total amount of the attached invoice INV-000001 is $190.00</p>",
    "notes_raw" : "<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>",
    "discount" : 5,
    "discount_type" : "percentage",
    "discount_val" : 1000,
    "tax" : 0,
    "sub_total" : 20000,
    "sent_at" : null,
    "viewed_at" : null,
    "approved_at" : null,
    "overdue_at" : null,
    "invoice_pdf_url" : "https://payments.your-domain.com/invoices/pdf/9aae0110-a4d6-4552-99de-4b4d3e3432f8",
    "attachments" : [],
    "customer" : {},
    "tax_per_item_enabled" : false,
    "discount_per_item_enabled" : false,
    "created_at" : 1687268840,
    "billing_address": {},
    "shipping_address": {},
    "paid_status" : "UNPAID",
    "total" : 19000,
    "due_amount" : 19000,
    "sent_to_oatfi": null,
    "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "scheduled_date": null,
    "payee_loan_status" : "DRAFT",
    "payor_loan_status" : "DRAFT",        
    "allowed_paid_invoice_states": [
        "PARTIALLY_PAID",
        "PAID"
    ],
    "integrations": [],
    "recurring_auto_pay_authorized": false
  }
}

GETapi/v1/invoices/{id}

Retrieve an invoice

This endpoint allows you to retrieve an invoice.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.

Request

GET

api/v1/invoices/{id}

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

Response

{
  "data" : {
    "id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
    "estimate_id": null,
    "invoice_number" : "INV-000001",
    "invoice_date" : 1017705600,
    "due_date" : 1594944000,
    "customer_business_id" : "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "template_name" : "invoice1",
    "items": [
      {
        "id": "9974c9fc-5dfc-4262-81b8-f42e3275119b",
        "name": "Laptop",
        "description": "New Laptop with latest features",
        "discount_type": null,
        "price": 10000,
        "quantity": 2,
        "unit_name": null,
        "discount": 0,
        "discount_val": 0,
        "tax": 0,
        "total": 20000,
        "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
        "item_id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
        "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
      }
    ],
    "sequence_number" : 1,
    "status" : "DRAFT",
    "notes" : "<p>The total amount of the attached invoice INV-000001 is $190.00</p>",
    "notes_raw" : "<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>",
    "discount" : 5,
    "discount_type" : "percentage",
    "discount_val" : 1000,
    "tax" : 0,
    "sub_total" : 20000,
    "sent_at" : null,
    "viewed_at" : null,
    "approved_at" : null,
    "overdue_at" : null,
    "invoice_pdf_url" : "https://payments.your-domain.com/invoices/pdf/9aae0110-a4d6-4552-99de-4b4d3e3432f8",
    "attachments" : [],
    "customer" : {},
    "tax_per_item_enabled" : false,
    "discount_per_item_enabled" : false,
    "created_at" : 1687268840,
    "billing_address": {},
    "shipping_address": {},
    "paid_status" : "UNPAID",
    "total" : 19000,
    "due_amount" : 19000,
    "sent_to_oatfi": null,
    "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "scheduled_date": null,
    "payee_loan_status" : "DRAFT",
    "payor_loan_status" : "DRAFT",
    "taxes": [],
    "vendor": {},
    "allowed_paid_invoice_states": [
        "PARTIALLY_PAID",
        "PAID"
    ],
    "integrations": [],
    "recurring_auto_pay_authorized": false
  }
}

PUTapi/v1/invoices/{id}

Update an invoice

This endpoint allows you to perform an update on invoice.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.

Body Parameters

Name
invoice_number
Type
string
Field Type
optional
Description
Invoice Number.
Name
invoice_date
Type
timestamp
Field Type
optional
Description
Date of the invoice.
Name
due_date
Type
timestamp
Field Type
optional
Description
Due Date.
Name
template_name
Type
string
Field Type
optional
Description
Name of the template to be used for the invoice PDF.
Name
discount
Type
float
Field Type
optional
Description
Discount value. Pass percentage of the discount or the amount if the discount is fixed in cents. Example: 10 (percentage) or 1000(fixed).
Name
discount_type
Type
string
Field Type
optional
Description
Type of discount: fixed or percentage.
Name
tax_type_ids
Type
array
Field Type
optional
Description
Array of Tax type IDs.
Name
notes
Type
string
Field Type
optional
Description
Invoice Notes.
Name
items[].name
Type
string
Field Type
optional
Description
Name of Item.
Name
items[].quantity
Type
integer
Field Type
optional
Description
Item Quantity.
Name
items[].price
Type
integer
Field Type
optional
Description
Item Price in cents.
Name
items[].description
Type
string
Field Type
optional
Description
Item Description.
Name
items[].item_id
Type
string
Field Type
optional
Description
Item ID.
Name
items[].unit_name
Type
string
Field Type
optional
Description
Item Unit Name.
Name
items[].discount
Type
float
Field Type
optional
Description
Actual discount value that appears on the PDF. Pass percentage of the discount or the amount if the discount is fixed.
Name
items[].discount_type
Type
string
Field Type
optional
Description
Type of discount: fixed or percentage.
Name
items[].tax_type_ids
Type
array
Field Type
optional
Description
Array of Tax type IDs.

Request

PUT

api/v1/invoices/{id}

curl --request PUT \
  "https://payments.your-domain.com/api/v1/invoices/9aae0110-a4d6-4552-99de-4b4d3e3432f8" \
  --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\",
    \"discount_type\": \"percentage\",
    \"discount\": \"5\",
    \"notes\": \"<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>\",
    \"template_name\": \"invoice1\",
    \"items\": [
      {
        \"name\": \"Apple Macbook\",
        \"quantity\": \"2\",
        \"price\": \"10000\",
        \"description\": \"Light and powerful laptop\",
        \"unit_name\": \"box\",
        \"discount\": \"0\",
        \"discount_type\": \"fixed\"
      }
    ]
  }"

Response

{
  "data" : {
    "id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
    "estimate_id": null,
    "invoice_number" : "INV-000001",
    "invoice_date" : 1017705600,
    "due_date" : 1594944000,
    "customer_business_id" : "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "template_name" : "invoice1",
    "items": [
      {
        "id": "9974c9fc-5dfc-4262-81b8-f42e3275119b",
        "name": "Apple Macbook",
        "description": "Light and powerful laptop",
        "discount_type": null,
        "price": 10000,
        "quantity": 2,
        "unit_name": null,
        "discount": 0,
        "discount_val": 0,
        "tax": 0,
        "total": 20000,
        "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
        "item_id": null,
        "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
      }
    ],
    "sequence_number" : 1,
    "status" : "DRAFT",
    "notes" : "<p>The total amount of the attached invoice INV-000001 is $190.00</p>",
    "notes_raw" : "<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>",
    "discount" : 5,
    "discount_type" : "percentage",
    "discount_val" : 1000,
    "tax" : 0,
    "sub_total" : 20000,
    "sent_at" : null,
    "viewed_at" : null,
    "approved_at" : null,
    "overdue_at" : null,
    "invoice_pdf_url" : "https://payments.your-domain.com/invoices/pdf/9aae0110-a4d6-4552-99de-4b4d3e3432f8",
    "attachments" : [],
    "customer" : {},
    "tax_per_item_enabled" : false,
    "discount_per_item_enabled" : false,
    "created_at" : 1687268840,
    "billing_address": {},
    "shipping_address": {},
    "paid_status" : "UNPAID",
    "total" : 19000,
    "due_amount" : 19000,
    "sent_to_oatfi": null,
    "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "scheduled_date": null,
    "payee_loan_status" : "DRAFT",
    "payor_loan_status" : "DRAFT",
    "taxes": [],
    "vendor": {},
    "allowed_paid_invoice_states": [
        "PARTIALLY_PAID",
        "PAID"
    ],
    "integrations": [],
    "recurring_auto_pay_authorized": false
  }
}

DELETEapi/v1/invoices/{id}

Delete invoice

This endpoint allows you to delete a specific invoice.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.

Request

DELETE

api/v1/invoices/{id}

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

Response

{
  "id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
  "object": "Invoice",
  "deleted": true
}

POSTapi/v1/invoices/{id}/send-email

Send an invoice

This endpoint allows you to send the invoice link to the corresponding customer's email address.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.

Body Parameters

Name
subject
Type
string
Field Type
required
Description
Subject of the email.
Name
body
Type
string
Field Type
required
Description
Body of the email.
Name
reply_to
Type
string
Field Type
required
Description
Reply to email address.
Name
to
Type
string
Field Type
required
Description
Email address of the recipient.

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\"
  }"

POSTapi/v1/invoices/{id}/clone

Clone an invoice

This endpoint allows you to clone invoice.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.

Request

POST

api/v1/invoices/{id}/clone

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

POSTapi/v1/invoices/{id}/approve

Approve an incoming invoice

This endpoint allows you mark an invoice as APPROVED.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.

Request

POST

api/v1/invoices/{id}/approve

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

POSTapi/v1/invoices/{id}/finalize

Finalize an invoice

This endpoint allows you mark an invoice as OPEN.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.

Request

POST

api/v1/invoices/{id}/finalize

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

POSTapi/v1/invoices/{id}/void

Void an invoice

This endpoint allows you mark an invoice as VOID.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.

Request

POST

api/v1/invoices/{id}/void

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

GETapi/v1/next-number

Next Sequence Number

This endpoint allows you to get the next Sequence Number for an Invoice.

Query Parameters

Name
model
Type
string
Field Type
required
Description
Must be invoice

Request

GET

api/v1/next-number

curl --request GET \
  "https://payments.your-domain.com/api/v1/next-number?model=invoice" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \

Response

{
  "next_number": "INV-000001",
  "next_sequence_number": 1
}

GETapi/v1/invoices/{id}/attachments

List all attachment of an invoice

This endpoint is used to get all attachments of an invoice.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.

Request

GET

api/v1/invoices/{id}/attachments

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

Response

{
  "data": [
    {
      "id": 17,
      "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
      "name": "logo-dark",
      "path": null,
      "url": null,
      "size": 151922,
      "mime_type": "image/png"
    }, {...}
  ]
}

POSTapi/v1/invoices/{id}/attachments

Add attachment to an invoice

This endpoint is used to upload an attachments to an invoice.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.

Body Parameters

Name
attachments
Type
array
Field Type
required
Description
Array of attachments to be uploaded.

Request

POST

api/v1/invoices/{id}/attachments

curl --request POST \
  "https://payments.your-domain.com/api/v1/invoices/9aae0110-a4d6-4552-99de-4b4d3e3432f8/attachments" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: multipart/form-data" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --form 'attachments[]=@"/path_to_attachment/crater_attachment.png"'

Response

{
  "data": [
    {
      "id": 17,
      "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
      "name": "crater_attachment.png",
      "path": null,
      "url": null,
      "size": 151922,
      "mime_type": "image/png"
    }
  ]
}

GETapi/v1/invoices/{id}/attachments/{attachment_id}

Retrieve attachment of an invoice

This endpoint is used to get all attachments of an invoice.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.
Name
attachment_id
Type
integer
Field Type
required
Description
The ID of the attachment.

Request

GET

api/v1/invoices/{id}/attachments/{attachment_id}

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

Response

{
  "data": [
    {
      "id": 17,
      "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
      "name": "logo-dark",
      "path": null,
      "url": null,
      "size": 151922,
      "mime_type": "image/png"
    }
  ]
}

DELETEapi/v1/invoices/{id}/attachments/{attachment_id}

Remove attachment from an invoice

This endpoint is used to remove attachment from invoice.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the invoice.
Name
attachment_id
Type
integer
Field Type
required
Description
The ID of the attachment.

Request

DELETE

api/v1/invoices/{id}/attachments/{attachment_id}

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

Response

{
  "id": 17,
  "object": "Attachment",
  "deleted": true,
}

The InvoiceLink model

Invoice Links serve as a convenient means for customers to access and interact with specific invoices. Generated with the invoice ID, these links enable customers to view, approve, or make payments directly. Streamlining the invoicing process, Invoice Links enhance communication and provide a user-friendly experience for customers engaging with their invoices.

Properties

Name
id
Type
string
Field Type
Description
Unique identifier for the invoice link.
Name
url
Type
string
Field Type
Description
The URL of the invoice link.
Name
expiry_date
Type
timestamp
Field Type
Description
The expiry date of the invoice link.

GETapi/v1/invoices/{invoice_id}/links

List all invoice links

This endpoint allows you to retrieve a paginated list of all links associated with the given invoice.

URL Parameters

Name
invoice_id
Type
string
Field Type
required
Description
The ID of the invoice.

Query Parameters

Name
limit
Type
integer
Field Type
optional
Description
A limit on the number of invoice links to be returned. (default is 5)
Name
page
Type
integer
Field Type
optional
Description
Page number for pagination. (default is 1)

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" \

Response

{
  "data": [
    {
      "id": "9ab7fb83-847a-4293-8cb9-f55eb29ab2d9",
      "url": "https://payments.your-domain.com/public/invoices/view/9ab7fb83-847a-4293-8cb9-f55eb29ab2d9?
        signature=e33c035bd56b9951f5191f6803fb5e03d46c1a014134b3a394dd80ca94665e43",
      "expiry_date": 1689565444,
      "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
    },
    {
      "id": "9990ee27-2ce2-46a4-87b8-545aea88cc55",
      "url": "https://payments.your-domain.com/public/invoices/view/9990ee27-2ce2-46a4-87b8-545aea88cc55?
        signature=e33c035bd56b9951f5191f6803fb5e03d46c1a014134b3a394dd80ca94665e43",
      "expiry_date": 1689565444,
      "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
    }
  ]
}

POSTapi/v1/invoices/{invoice_id}/links

Create an invoice link

This endpoint allows you to create new invoice link.

URL Parameters

Name
invoice_id
Type
string
Field Type
required
Description
The id of the invoice.

Body Parameters

Name
expiry_date
Type
timestamp
Field Type
optional
Description
The expiry date of the invoice link.
Must not exceed 7 days from the current date. (default expiry is 1 hour from the current date if not specified)

Request

POST

api/v1/invoices/{invoice_id}/links

curl --request POST \
  "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" \
  --data '{"expiry_date": "1689565444"}' \

Response

{
  "data": {
    "id": "9ab7fb83-847a-4293-8cb9-f55eb29ab2d9",
    "url": "https://payments.your-domain.com/public/invoices/view/9ab7fb83-847a-4293-8cb9-f55eb29ab2d9?
      signature=e33c035bd56b9951f5191f6803fb5e03d46c1a014134b3a394dd80ca94665e43",
    "expiry_date": 1689565444,
    "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
  }
}

GETapi/v1/invoices/{invoice_id}/links/{invoice_link_id}

Retrieve an invoice link

This endpoint allows you to retrieve an existing invoice link.

URL Parameters

Name
invoice_id
Type
string
Field Type
required
Description
The id of the invoice.
Name
invoice_link_id
Type
string
Field Type
required
Description
The id of the invoice link.

Request

GET

api/v1/invoices/{invoice_id}/links/{invoice_link_id}

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

Response

{
  "data": {
    "id": "9ab7fb83-847a-4293-8cb9-f55eb29ab2d9",
    "url": "https://payments.your-domain.com/public/invoices/view/9ab7fb83-847a-4293-8cb9-f55eb29ab2d9?
      signature=e33c035bd56b9951f5191f6803fb5e03d46c1a014134b3a394dd80ca94665e43",
    "expiry_date": 1689565444,
    "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
  }
}

DELETEapi/v1/invoices/{invoice_id}/links/{invoice_link_id}

Delete an invoice link

This endpoint allows you to delete a specific invoice link

URL Parameters

Name
invoice_id
Type
string
Field Type
required
Description
The id of the invoice.
Name
invoice_link_id
Type
string
Field Type
required
Description
The id of the invoice link.

Request

DELETE

api/v1/invoices/{invoice_id}/links/{invoice_link_id}

curl --request DELETE \
  "https://payments.your-domain.com/api/v1/invoices/9aae0110-a4d6-4552-99de-4b4d3e3432f8/links/9ab7fb83-847a-4293-8cb9-f55eb29ab2d9" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \

Response

{
  "id": "9ab7fb83-847a-4293-8cb9-f55eb29ab2d9",
  "object": "InvoiceLink",
  "deleted": true
}