📃Invoices
Introduction
Invoices are a powerful tool for businesses to bill customers for goods or services. Sonic Payment Gateway provides a simple and secure way to create, manage, and track invoices. In this section, we will cover how to create, retrieve, update, and delete invoices using our API.
Create an invoice
To create an invoice, you will need to make a POST request to the /invoices endpoint. You can include the following parameters in the request body:
amount
integer
The total amount of the invoice in the smallest denomination of the currency (e.g. cents for USD)
currency
string
The ISO 4217 currency code
customer_email
string
The email address of the customer
customer_name
string
The name of the customer
line_items
array
An array of line items for the invoice. Each line item should include the following parameters: name, amount, and quantity.
due_date
string (YYYY-MM-DD)
The date the invoice is due in ISO 8601 format
metadata
object
Additional metadata to associate with the invoice
Creating an invoice
POST https://api.sonicpay.org/invoices
Request Body
amount*
10000
currency*
USDT
customer_email*
customer@example.com
customer_name*
John Doe
line_items*
"name": "Product 1", "amount": 5000, "quantity": 2
due_date*
2022-05-30
metadata*
"order_id": "12345"
{
"id": "f6a2f7f-3400-4f47-8973-fa8bb2f5d483",
"reference": "INV-12345",
"amount": 10000,
"currency": "USDT",
"status": "Paid",
"metadata": {
"customer_name": "John Doe"
},
"createdAt": "2022-07-01T12:00:00.000Z",
"updatedAt": "2022-07-01T12:00:00.000Z"
}Here is an example curl request for creating an invoice:
curl --location --request POST 'https://api.sonicpay.org/invoices' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": 10000,
"currency": "USDT",
"customer_email": "customer@example.com",
"customer_name": "John Doe",
"line_items": [
{
"name": "Product 1",
"amount": 5000,
"quantity": 2
},
{
"name": "Product 2",
"amount": 2500,
"quantity": 1
}
],
"due_date": "2022-05-30",
"metadata": {
"order_id": "12345"
}
}'
Get an invoice
To retrieve an invoice, you will need to make a GET request to the /invoices/{invoice_id} endpoint, where {invoice_id} is the ID of the invoice you wish to retrieve.
GET https://api.sonicpay.org/invoices/invoice_id
Path Parameters
invoice_id*
32322
Headers
Content-Type*
application/json
Authorization: Bearer*
your_api_key
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "5f0efa72-f2b9-4b5d-9c1b-8f8f1e0b0c2d",
"name": "Invoice 1",
"description": "This is an invoice for product 1",
"amount": 100,
"currency": "Doge",
"created_at": "2022-01-19T00:00:00.000Z",
"updated_at": "2022-01-19T00:00:00.000Z",
"status": "paid"
}
Update an invoice
To update an invoice, you will need to make a PUT request to the /invoices/{invoice_id} endpoint, where {invoice_id} is the ID of the invoice you wish to update. You can include any of the parameters from the create invoice request in the request body.
PATCH PATCH https://api.sonicpay.org/invoices/{invoice_id}
Path Parameters
invoice_id*
23424
Authorization: Bearer*
your_api_key
Content-Type*
application/json
Request Body
description*
New Description
amount*
100
currency*
Doge
shipping*
Pending
metadata*
"order_id": "12345"
{
"id": "invoice_id",
"description": "New Description",
"amount": 15.5,
"currency": "USD",
"status": "unpaid",
"created_at": "2022-09-05T16:35:22.986Z",
"updated_at": "2022-09-05T16:35:22.986Z",
"shipping": {
"amount": 2,
"address": {
"name": "John Smith",
"address1": "123 Main St",
"address2": "Apt 456",
"city": "San Francisco",
"state": "CA",
"country": "US",
"postal_code": "94105"
}
},
"metadata": {
"order_id": "12345"
}
}This endpoint is used to update an existing invoice. The following parameters can be updated:
description
string
A description of the invoice
amount
number
The total amount of the invoice
currency
string
The currency of the invoice (e.g. USD, EUR, etc.)
shipping
object
An object containing information about the shipping costs associated with the invoice. Can contain the following properties:<br>- amount: The amount of the shipping costs<br>- address: An object containing information about the shipping address. Can contain the following properties:<br> - name: The name of the recipient<br> - address1: The first line of the shipping address<br> - address2: The second line of the shipping address (optional)<br> - city: The city of the shipping address<br> - state: The state of the shipping address<br> - country: The country of the shipping address<br> - postal_code: The postal code of the shipping address
metadata
object
An object containing additional information about the invoice
Example Request
curl -X PATCH https://api.sonicpay.org/invoices/invoice_id \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"description": "New Description",
"amount": 15.5,
"shipping": {
"amount": 2,
"address": {
"name": "John Smith",
"address1": "123 Main St",
"address2": "Apt 456",
"city": "San Francisco",
"state": "CA",
"country": "US",
"postal_code": "94105"
}
},
"metadata": {
"order_id": "12345"
}
}'
Example Response:
{
"id": "invoice_id",
"description": "New Description",
"amount": 15.5,
"currency": "USD",
"status": "unpaid",
"created_at": "2022-09-05T16:35:22.986Z",
"updated_at": "2022-09-05T16:35:22.986Z",
"shipping": {
"amount": 2,
"address": {
"name": "John Smith",
"address1": "123 Main St",
"address2": "Apt 456",
"city": "San Francisco",
"state": "CA",
"country": "US",
"postal_code": "94105"
}
},
"metadata": {
"order_id": "12345"
}
}
Get all Invoices
Make a GET request to the /invoices endpoint. This will return a list of all invoices associated with your account, including their ID, status, and amount.
GET https://api.sonicpay.org/v1/invoices
Headers
Authorization: Bearer
YOUR_API_KEY
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 10,
"page": 1,
"per_page": 20
},
"data": [
{
"id": "5f0efa72-f2b9-4b5d-9c1b-8f8f1e0b0c2d",
"name": "Invoice 1",
"description": "This is an invoice for product 1",
"amount": 100,
"currency": "USDC",
"created_at": "2022-01-19T00:00:00.000Z",
"updated_at": "2022-01-19T00:00:00.000Z",
"status": "paid"
},
{
"id": "5f0efa72-f2b9-4b5d-9c1b-8f8f1e0b0c2e",
"name": "Invoice 2",
"description": "This is an invoice for product 2",
"amount": 200,
"currency": "USDC",
"created_at": "2022-01-19T00:00:00.000Z",
"updated_at": "2022-01-19T00:00:00.000Z",
"status": "unpaid"
}
]
}
curl -X GET https://api.sonicpay.org/v1/invoices \
-H 'Authorization: Bearer YOUR_API_KEY'
You can also include query parameters to filter the invoices returned in the response. For example, you can filter by invoice status (paid, unpaid, etc) or by a specific date range.
curl -X GET https://api.sonicpay.org/v1/invoices?status=paid&start_date=2022-01-01&end_date=2022-12-31 \
-H 'Authorization: Bearer YOUR_API_KEY'Alternatively, you can use the Sonic Payment Gateway SDK to get all invoices in your desired programming language. The SDK will handle the API call and return the result in a format that is easy to work with in your code.
sonicPayment.getAllInvoices(
{
status: "paid",
start_date: "2022-01-01",
end_date: "2022-12-31",
},
(error, invoices) => {
if (error) {
console.log(error);
} else {
console.log(invoices);
}
}
);
Response:
{
"invoices": [
{
"id": "inv_1D5sV2eZgKYlo2C",
"status": "paid",
"amount": 100,
"date": "2022-05-01T12:00:00Z",
"payment_link_id": "pl_1D5sV2eZgKYlo2C",
"metadata": {
"customer_name": "John Doe"
}
},
{
"id": "inv_1D5sV2eZgKYlo2C",
"status": "paid",
"amount": 50,
"date": "2022-05-15T12:00:00Z",
"payment_link_id": "pl_1D5sV2eZgKYlo2C",
"metadata": {
"customer_name": "Jane Smith"
}
}
]
}
Last updated