Create an invoice
TEOS API consumers can create an invoice to get a digital record for agreed obligation of payment and pay invoice to fulfil this obligation. Invoice is a time-stamped digital record for a payment agreement made between two parties.
An invoice defines the obligation of a sender to transfer a specified amount of an asset (in sparks) to a target address before the due date.
Once created, the invoice remains in the Open status until it is either paid, expired, canceled, or fails.
📘 Learn more about invoices.
Request Endpoint
POST /odata/v1.0/Invoices
Parameters
No query parameters.
Request Body
Content type: application/json — Invoice details to be created.
| Parameter | Type | Description | Mandatory |
|---|---|---|---|
| UniqueAssetId | string | Unique ID of the asset to be used for the payment. | ✅ |
| TargetAddress | string | Wallet address that will receive the payment. Must be a valid blockchain address (length depends on network type). | ✅ |
| DesiredAmount | string | Amount of the asset (in sparks) to be transferred when the invoice is paid. | ✅ |
| DueOn | string (ISO date) | Due date for the invoice validity. After this date, status automatically changes to Expired. | ✅ |
| Description | string | Optional text or JSON description of the invoice purpose. | ❌ |
Example Request Body
In EVM-compatible networks (e.g., Sparknet, Ethereum, and Polygon), the "TargetAddress" is 42 characters long. In non-EVM networks, the address length may differ. For example, on Internet Computer, it is 63 characters.
{
"UniqueAssetId": "0x96d45a5c311f13c97fca0001",
"TargetAddress": "0x71ea8b6b06b5a832817eb574b4fed3defb41046e",
"DesiredAmount": "10000000",
"DueOn": "2022-05-10T13:30:00Z",
"Description": "Some description or json"
}
Response Body
Content type: application/json — Returns the created invoice details.
| Parameter | Description |
|---|---|
| Id | Unique identifier of the created invoice. |
| Status | Current status of the invoice (Open, Processing, Paid, Expired, Cancelled, Failed). |
| UniqueAssetId | Asset ID used for the invoice payment. |
| DesiredAmount | Amount of sparks specified for payment. |
| TargetAddress | Wallet address that will receive the payment. |
| SenderAddress | Wallet address responsible for paying the invoice (empty until payment is initiated). |
| Description | Optional description of the invoice. |
| CreatedBy | ID of the user who created the invoice. |
| CreatedOn | Date and time when the invoice was created. |
| UpdatedOn | Date and time when the invoice was last updated. |
| DueOn | Date and time after which the invoice expires if unpaid. |
| TransactionId | Identifier of the transaction created when the invoice is paid. |
Example Response Body
In EVM-compatible networks (e.g., Sparknet, Ethereum, and Polygon), the "TargetAddress"and "SenderAddress" are 42 characters long. In non-EVM networks, the address length may differ. For example, on Internet Computer, it is 63 characters.
{
"Id": "C0D34D73-6FD3-40F2-A7E1-08D9412448F7",
"Status": "Open",
"UniqueAssetId": "0x096d45a5c311f13c97fca0001",
"DesiredAmount": "100000",
"TargetAddress": "0x0972b2d2a189225e6bbe8680283e5c62c2309819",
"SenderAddress": "0x0000000000000000000000000000000000000000",
"Description": "string",
"CreatedBy": "37514BE7-D096-4BB8-95DA-EDB03B723BB2",
"CreatedOn": "2022-07-21T09:40:23.263Z",
"UpdatedOn": "2022-07-21T09:40:23.263Z",
"DueOn": "2023-08-04T09:40:22.32Z",
"TransactionId": "00000000-0000-0000-0000-000000000000"
}
Response Codes
| Code | Description |
|---|---|
| 201 | The invoice was created successfully. |
| 400 | The provided invoice data is invalid. Error details are included. |
| 401 | Unauthorized. |