Recurring 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 Recurring Invoice model

Recurring 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 recurring invoice.
Name
start_date
Type
timestamp
Field Type
Description
Start Date.
Name
end_date
Type
timestamp
Field Type
Description
End Date.
Name
customer_business_id
Type
string
Field Type
Description
Customer Business ID.
Name
send_automatically
Type
boolean
Field Type
Description
It specifies whether we can send invoices automatically.
Name
auto_pay_enabled
Type
boolean
Field Type
Description
Specifies whether to display an option to enable automatic payment when the customer pays the first invoice.
Name
status
Type
string
Field Type
Description
Status of the recurring invoice.
Must be one of COMPLETED, ON_HOLD, or ACTIVE.
Name
template_name
Type
string
Field Type
Description
Name of the template to be used for the invoice PDF.
Name
items
Type
object
Field Type
Description
Recurring invoice items object
Name
repeat_interval
Type
string
Field Type
Description
Repeat interval.
Name
week_day
Type
string
Field Type
Description
Day of the week.
Name
month
Type
string
Field Type
Description
Month.
Name
day_of_month
Type
string
Field Type
Description
Day of the month.
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
sub_total
Type
integer
Field Type
Description
Subtotal in cents.
Name
tax
Type
integer
Field Type
Description
Tax in cents.
Name
total
Type
integer
Field Type
Description
Total in cents.
Name
vendor_business_id
Type
string
Field Type
Description
Vendor Business ID.
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.

GETapi/v1/recurring-invoices

List all recurring invoices

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

Query Parameters

Name
limit
Type
integer
Field Type
optional
Description
Limit the number of recurring 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.
Must be one of COMPLETED, ON_HOLD, or ACTIVE.
Name
customer_business_id
Type
string
Field Type
optional
Description
Filter by customer_business_id (Only fetch recurring invoices of a given customer of this business)
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/recurring-invoices

curl --request GET \
  --get "https://payments.your-domain.com/api/v1/recurring-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": "9b12f8be-ce9d-40b6-b030-4c25d68b3e11",
      "start_date": 1705140000,
      "end_date": 1706695200,
      "customer_business_id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
      "send_automatically": true,
      "auto_pay_enabled": false,
      "status": "ACTIVE",
      "template_name": "invoice1",
      "items": [],
      "repeat_interval": "Weekly",
      "week_day": "Monday",
      "month": null,
      "day_of_month": null,
      "notes": "<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>",
      "discount": 5,
      "discount_type": "percentage",
      "discount_val": 1000,
      "sub_total": 20000,
      "tax": 0,
      "total": 19000,
      "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "tax_per_item_enabled": false,
      "discount_per_item_enabled": false,
      "formatted_start_date": "13 Jan 2024",
      "formatted_created_at": "12 Jan 2024",
      "formatted_end_date": "31 Jan 2024",
      "formatted_limit_date": "12 Jan 2024",
      "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
      "timezone": "America/New_York",
      "customer": {},
      "vendor": {},
      "taxes": []
    }, {...}
  ]
}

POSTapi/v1/recurring-invoices

Create a recurring invoice

This endpoint allows you to create a recurring invoice.

Body Parameters

Name
start_date
Type
timestamp
Field Type
required
Description
Start Date.
Name
end_date
Type
timestamp
Field Type
required
Description
End Date.
Name
customer_business_id
Type
string
Field Type
required
Description
Customer Business ID.
Name
send_automatically
Type
boolean
Field Type
required
Description
It specifies whether we can send invoices automatically.
Name
auto_pay_enabled
Type
boolean
Field Type
required
Description
Specifies whether to display an option to enable automatic payment when the customer pays the first invoice.
Name
status
Type
string
Field Type
required
Description
Status of recurring invoice.
Must be one of COMPLETED, ON_HOLD, or ACTIVE.
Name
template_name
Type
string
Field Type
required
Description
Name of the template to be used for the invoice PDF.
Name
repeat_interval
Type
string
Field Type
required
Description
Repeat interval.
Name
week_day
Type
string
Field Type
required if repeat_interval is Weekly
Description
Day of the week.
Name
month
Type
string
Field Type
required if repeat_interval is Yearly
Description
Month.
Name
day_of_month
Type
string
Field Type
required if repeat_interval is Yearly or Monthly
Description
Day of the month.
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/recurring-invoices

curl --request POST \
  "https://payments.your-domain.com/api/v1/recurring-invoices" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"start_date\": 1705122000,
    \"end_date\": 1706677200,
    \"status\": \"ACTIVE\",
    \"repeat_interval\": \"Weekly\",
    \"week_day\": \"Monday\",
    \"send_automatically\": true,
    \"auto_pay_enabled\": false,
    \"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": "9b12f8be-ce9d-40b6-b030-4c25d68b3e11",
    "start_date": 1705140000,
    "end_date": 1706695200,
    "customer_business_id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "send_automatically": true,
    "auto_pay_enabled": false,
    "status": "ACTIVE",
    "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,
        "recurring_invoice_id": "9b12f8be-ce9d-40b6-b030-4c25d68b3e11",
        "item_id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
        "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
        "approved": 0 
      }
    ],
    "repeat_interval": "Weekly",
    "week_day": "Monday",
    "month": null,
    "day_of_month": null,
    "notes": "<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>",
    "discount": 5,
    "discount_type": "percentage",
    "discount_val": 1000,
    "sub_total": 20000,
    "tax": 0,
    "total": 19000,
    "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "tax_per_item_enabled": false,
    "discount_per_item_enabled": false,
    "formatted_start_date": "13 Jan 2024",
    "formatted_created_at": "12 Jan 2024",
    "formatted_end_date": "31 Jan 2024",
    "formatted_limit_date": "12 Jan 2024",
    "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "timezone": "America/New_York",
    "customer": {},
    "vendor": {},
    "taxes": []
  }
}

GETapi/v1/recurring-invoices/{id}

Retrieve a recurring invoice

This endpoint allows you to retrieve an invoice.

URL Parameters

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

Request

GET

api/v1/recurring-invoices/{id}

curl --request GET \
  --get "https://payments.your-domain.com/api/v1/recurring-invoices/9b12f8be-ce9d-40b6-b030-4c25d68b3e11" \
  --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": "9b12f8be-ce9d-40b6-b030-4c25d68b3e11",
    "start_date": 1705140000,
    "end_date": 1706695200,
    "customer_business_id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "send_automatically": true,
    "auto_pay_enabled": false,
    "status": "ACTIVE",
    "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,
        "recurring_invoice_id": "9b12f8be-ce9d-40b6-b030-4c25d68b3e11",
        "item_id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
        "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
        "approved": 0
      }
    ],
    "repeat_interval": "Weekly",
    "week_day": "Monday",
    "month": null,
    "day_of_month": null,
    "notes": "<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>",
    "discount": 5,
    "discount_type": "percentage",
    "discount_val": 1000,
    "sub_total": 20000,
    "tax": 0,
    "total": 19000,
    "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "tax_per_item_enabled": false,
    "discount_per_item_enabled": false,
    "formatted_start_date": "13 Jan 2024",
    "formatted_created_at": "12 Jan 2024",
    "formatted_end_date": "31 Jan 2024",
    "formatted_limit_date": "12 Jan 2024",
    "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "timezone": "America/New_York",
    "customer": {},
    "vendor": {},
    "taxes": []
  }
}

PUTapi/v1/recurring-invoices/{id}

Update a recurring invoice

This endpoint allows you to perform an update on recurring invoice.

URL Parameters

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

Body Parameters

Name
start_date
Type
timestamp
Field Type
optional
Description
Start Date.
Name
end_date
Type
timestamp
Field Type
optional
Description
End Date.
Name
send_automatically
Type
boolean
Field Type
optional
Description
It specifies whether we can send invoices automatically.
Name
auto_pay_enabled
Type
boolean
Field Type
optional
Description
Specifies whether to display an option to enable automatic payment when the customer pays the first invoice.
Name
status
Type
string
Field Type
optional
Description
Status of recurring invoice.
Must be one of COMPLETED, ON_HOLD, or ACTIVE.
Name
template_name
Type
string
Field Type
optional
Description
Name of the template to be used for the invoice PDF.
Name
repeat_interval
Type
string
Field Type
optional
Description
Repeat interval.
Name
week_day
Type
string
Field Type
required if repeat_interval is Weekly
Description
Day of the week.
Name
month
Type
string
Field Type
required if repeat_interval is Yearly
Description
Month.
Name
day_of_month
Type
string
Field Type
required if repeat_interval is Yearly or Monthly
Description
Day of the month.
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/recurring-invoices/{id}

curl --request PUT \
  "https://payments.your-domain.com/api/v1/recurring-invoices/9b12f8be-ce9d-40b6-b030-4c25d68b3e11" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"start_date\": 1705122000,
    \"end_date\": 1737453600,
    \"status\": \"ACTIVE\",
    \"repeat_interval\": \"Yearly\",
    \"day_of_month\": 20,
    \"month\": \"January\",
    \"send_automatically\": true,
    \"auto_pay_enabled\": false,
    \"discount_type\": \"percentage\",
    \"discount\": \"5\",
    \"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": "9b12f8be-ce9d-40b6-b030-4c25d68b3e11",
    "start_date": 1705140000,
    "end_date": 1737453600,
    "customer_business_id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "send_automatically": true,
    "auto_pay_enabled": false,
    "status": "ACTIVE",
    "template_name": "invoice1",
    "items": [
      {
        "id": "9974c9fc-5dfc-4262-81b8-f42e3275119b",
        "name": "Apple Macbook",
        "description": "Light and powerful laptop",
        "discount_type": "fixed",
        "price": 10000,
        "quantity": 2,
        "unit_name": "box",
        "discount": 0,
        "discount_val": 0,
        "tax": 0,
        "total": 20000,
        "recurring_invoice_id": "9b12f8be-ce9d-40b6-b030-4c25d68b3e11",
        "item_id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
        "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
        "approved": 0
      }
    ],
    "repeat_interval": "Yearly",
    "week_day": null,
    "month": "January",
    "day_of_month": 20,
    "notes": "<p>The total amount of the attached invoice {INVOICE_NUMBER} is {TOTAL_AMOUNT}</p>",
    "discount": 5,
    "discount_type": "percentage",
    "discount_val": 1000,
    "sub_total": 20000,
    "tax": 0,
    "total": 19000,
    "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "tax_per_item_enabled": false,
    "discount_per_item_enabled": false,
    "formatted_start_date": "13 Jan 2024",
    "formatted_created_at": "12 Jan 2024",
    "formatted_end_date": "21 Jan 2025",
    "formatted_limit_date": "12 Jan 2024",
    "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "timezone": "America/New_York",
    "customer": {},
    "vendor": {},
    "taxes": []
  }
}

DELETEapi/v1/recurring-invoices/{id}

Delete recurring invoice

This endpoint allows you to delete a specific recurring invoice.

URL Parameters

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

Request

DELETE

api/v1/recurring-invoices/{id}

curl --request DELETE \
  "https://payments.your-domain.com/api/v1/recurring-invoices/9b12f8be-ce9d-40b6-b030-4c25d68b3e11" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \

Response

{
  "id": "9b12f8be-ce9d-40b6-b030-4c25d68b3e11",
  "object": "RecurringInvoice",
  "deleted": true
}