Transactions
Create invoices and credit notes, retrieve them, and cancel a transaction.
A transaction is an invoice (type: debit) or a credit note (type: credit). Create it as a pending draft or finalized in one call and finalizing runs the tax engine and returns subtotal, tax and total. A credit note sets type: credit and references the original invoice with original_transaction_id.
Create an invoice (type: debit) or a credit note (type: credit), as a pending draft or finalized in one call. A finalized request runs the tax engine and returns subtotal, tax and total. Re-posting the same external_id updates the transaction.
Body for POST /v1/transactions. external_id is the natural
idempotency key. customer_id / product_id / original_transaction_id
all reference the caller's own external ids (never Sphere PKs). The customer
and each line's product are created if missing, and the inline detail here
(customer_name / customer_email / customer_tax_ids /
customer_tax_exempt / billing_address and each line's
product_name / product_tax_code) is applied whenever sent — omitted
fields keep the record's current value.
ISO 4217 currency code, e.g. USD.
nullnullnullnullnullnullnullA transaction. subtotal, tax and total appear once finalized, and original_transaction_id only on credit notes.
nullnullnullnullnullnullnullnullnullValidation error, keyed by the failing field.
Missing, invalid, or inactive API key, or a key not provisioned for the Transaction API.
Rate limit exceeded. Carries Retry-After and RateLimit-* headers.
POST /v1/transactions HTTP/1.1
Host: api.getsphere.com
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 850
{
"external_id": "text",
"type": "debit",
"status": "pending",
"currency": "text",
"customer_id": "text",
"finalized_on": "2026-01-01T00:00:00.000Z",
"external_reference_number": "text",
"billing_address": {
"address1": "text",
"address2": "text",
"city": "text",
"state": "text",
"postal_code": "text",
"country": "text"
},
"shipping_address": {
"address1": "text",
"address2": "text",
"city": "text",
"state": "text",
"postal_code": "text",
"country": "text"
},
"line_items": [
{
"external_id": "text",
"product_id": "text",
"amount": "text",
"discount_amount": "0",
"quantity": "text",
"unit_price": "text",
"description": "text",
"tax_inclusive": false,
"product_name": "text",
"product_tax_code": "text"
}
],
"original_transaction_id": "text",
"description": "text",
"customer_name": "text",
"customer_email": "text",
"customer_tax_ids": [
{
"tax_id": "text",
"country": "text",
"secondary_id": "text"
}
],
"customer_tax_exempt": true
}{
"external_id": "text",
"type": "text",
"status": "text",
"currency": "text",
"external_reference_number": "text",
"description": "text",
"customer_id": "text",
"finalized_on": "text",
"line_items": [
{
"external_id": "text",
"product_id": "text",
"amount": "text",
"discount_amount": "text",
"quantity": "text",
"unit_price": "text",
"description": "text",
"tax": "text"
}
],
"original_transaction_id": "text",
"subtotal": "text",
"tax": "text",
"total": "text",
"invoice_url": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}Base for every public v1 endpoint (products, and customers/transactions later) — named for the surface, not any one resource.
The external_id you assigned to the record.
A transaction. subtotal, tax and total appear once finalized, and original_transaction_id only on credit notes.
nullnullnullnullnullnullnullnullnullMissing, invalid, or inactive API key, or a key not provisioned for the Transaction API.
No record with that external_id.
Rate limit exceeded. Carries Retry-After and RateLimit-* headers.
GET /v1/transactions/{external_id} HTTP/1.1
Host: api.getsphere.com
X-API-KEY: YOUR_API_KEY
Accept: */*
{
"external_id": "text",
"type": "text",
"status": "text",
"currency": "text",
"external_reference_number": "text",
"description": "text",
"customer_id": "text",
"finalized_on": "text",
"line_items": [
{
"external_id": "text",
"product_id": "text",
"amount": "text",
"discount_amount": "text",
"quantity": "text",
"unit_price": "text",
"description": "text",
"tax": "text"
}
],
"original_transaction_id": "text",
"subtotal": "text",
"tax": "text",
"total": "text",
"invoice_url": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}Voids a transaction so it no longer contributes to your tax liability. No request body is needed, and the call is idempotent (re-cancelling returns the original cancelled_at).
The external_id you assigned to the record.
A cancelled transaction.
nullMissing, invalid, or inactive API key, or a key not provisioned for the Transaction API.
No record with that external_id.
Rate limit exceeded. Carries Retry-After and RateLimit-* headers.
POST /v1/transactions/{external_id}/cancel HTTP/1.1
Host: api.getsphere.com
X-API-KEY: YOUR_API_KEY
Accept: */*
{
"external_id": "text",
"status": "text",
"cancelled_at": "text"
}Last updated
Was this helpful?