API Resources
Seven object types, all with the same shape of endpoints. Replace <resource> below with any of customers, suppliers, categories, products, expenses, revenue, refunds.
| Endpoint | Does | Scope |
|---|---|---|
POST /v1/<resource> | Create. Requires Idempotency-Key. | write |
GET /v1/<resource> | List, newest first. | read |
GET /v1/<resource>/<id> | Retrieve one. | read |
POST /v1/<resource>/<id> | Update. Only while pending. | write |
DELETE /v1/<resource>/<id> | Withdraw your push. Only while pending. | write |
POST /v1/<resource>/<id>/reject | Mark as declined by the merchant. | write |
Expenses and revenue additionally have GET and POST /v1/<resource>/<id>/line_items.
Fields Every Object Has
| Field | Type | Notes |
|---|---|---|
id | string | Prefixed and opaque, for example cus_9f21c0b47ae35d18f2c4a7bb. |
object | string | The type name, so a mixed list is easy to switch on. |
created, updated | integer | Unix timestamps. |
import | object | status, batch, imported_at, local_ref. See Imports. |
Filter any list by import_status=pending|imported|rejected.
Customer
/v1/customers, ids start with cus_.
| Field | Type | Required |
|---|---|---|
name |
string (max 255) | Yes |
email |
string (email) | |
phone |
string (max 50) | |
company |
string (max 255) | |
tax_number |
string (max 60) | |
address_line1 |
string (max 255) | |
address_line2 |
string (max 255) | |
city |
string (max 120) | |
state |
string (max 120) | |
postal_code |
string (max 30) | |
country |
string (ISO 3166-1, 2 letters) | |
notes |
string (long) | |
metadata |
object (string values) |
List filters:
email, name
Supplier
/v1/suppliers, ids start with sup_.
| Field | Type | Required |
|---|---|---|
name |
string (max 255) | Yes |
email |
string (email) | |
phone |
string (max 50) | |
website |
string (max 255) | |
tax_number |
string (max 60) | |
address_line1 |
string (max 255) | |
address_line2 |
string (max 255) | |
city |
string (max 120) | |
state |
string (max 120) | |
postal_code |
string (max 30) | |
country |
string (ISO 3166-1, 2 letters) | |
notes |
string (long) | |
metadata |
object (string values) |
List filters:
email, name
Category
/v1/categories, ids start with cat_.
| Field | Type | Required |
|---|---|---|
name |
string (max 255) | Yes |
kind |
enum (expense, revenue) | Yes |
parent |
string (id of a category, cat_...) | |
description |
string (long) | |
metadata |
object (string values) |
List filters:
kind, name, parent
Product
/v1/products, ids start with prd_.
| Field | Type | Required |
|---|---|---|
name |
string (max 255) | Yes |
sku |
string (max 120) | |
description |
string (long) | |
unit |
string (max 40) | |
unit_amount |
integer (minor units) | |
currency |
string (ISO 4217, 3 letters) | |
tax_rate |
number | |
category |
string (id of a category, cat_...) | |
metadata |
object (string values) |
List filters:
sku, name, category
Expense
/v1/expenses, ids start with exp_.
| Field | Type | Required |
|---|---|---|
description |
string (max 500) | Yes |
amount |
integer (minor units) | Yes |
currency |
string (ISO 4217, 3 letters) | Yes |
tax_amount |
integer (minor units) | |
occurred_on |
string (YYYY-MM-DD) | Yes |
supplier |
string (id of a supplier, sup_...) | |
category |
string (id of a category, cat_...) | |
payment_method |
string (max 40) | |
reference |
string (max 120) | |
notes |
string (long) | |
metadata |
object (string values) |
List filters:
supplier, category, currency, reference, occurred_on (also [gte], [gt], [lte], [lt])
Revenue
/v1/revenue, ids start with rev_.
| Field | Type | Required |
|---|---|---|
description |
string (max 500) | Yes |
amount |
integer (minor units) | Yes |
currency |
string (ISO 4217, 3 letters) | Yes |
tax_amount |
integer (minor units) | |
discount_amount |
integer (minor units) | |
fee_amount |
integer (minor units) | |
occurred_on |
string (YYYY-MM-DD) | Yes |
customer |
string (id of a customer, cus_...) | |
category |
string (id of a category, cat_...) | |
payment_method |
string (max 40) | |
reference |
string (max 120) | |
notes |
string (long) | |
metadata |
object (string values) |
List filters:
customer, category, currency, reference, occurred_on (also [gte], [gt], [lte], [lt])
Refund
/v1/refunds, ids start with re_.
| Field | Type | Required |
|---|---|---|
revenue |
string (id of a revenue, rev_...) | Yes |
amount |
integer (minor units) | Yes |
currency |
string (ISO 4217, 3 letters) | Yes |
reason |
string (max 255) | |
occurred_on |
string (YYYY-MM-DD) | Yes |
reference |
string (max 120) | |
metadata |
object (string values) |
List filters:
revenue, currency, occurred_on (also [gte], [gt], [lte], [lt])
Line item
A sub-object of an expense or revenue. Retrieved with expand[]=line_items or its own endpoint. Line items have no import status of their own; they follow their parent.
| Field | Type | Required |
|---|---|---|
product |
string (id of a product, prd_...) | |
description |
string (max 500) | Yes |
quantity |
number | |
unit_amount |
integer (minor units) | Yes |
tax_amount |
integer (minor units) | |
discount_amount |
integer (minor units) |
Rules Worth Knowing Before You Hit Them
tax_amountcannot exceedamount. Amounts are gross, tax included.- A refund must use the same currency as the revenue it refunds, and the total refunded can never exceed the original. The error tells you how much is still refundable.
- A reference to an object that does not exist is rejected on the request that made it, not silently at import time.
- Passing a field we do not recognise is a
400naming the field. A typo in an optional parameter should not be something you discover in three weeks. fee_amounton revenue is for a platform's withheld cut. It becomes a separate expense in the merchant's books, so the sale keeps its gross value.