Products

Create products, assign Sphere product tax codes, and retrieve them.

A product represents something you sell. Assign a Sphere product tax code so the tax engine can determine taxability and rates. Reference a product as product_id on a transaction line.

Create or update a product

post

/products

Creates a product, or merges into the existing one with the same external_id. Assign a Sphere product tax code so the engine can determine taxability and rates. With an API key associated to a billing integration connection, external_id is that system's product idand the write updates the synced product in place.

Authorizations

X-API-KEYstringRequired

Body

Body for POST /v1/products.

external_id is the caller's own product identifier and doubles as the natural idempotency key: re-posting the same external_id updates the existing product (merge — only the fields you send change).

external_idstring · min: 1 · max: 255Required

namestring · max: 1024 · nullableOptionalDefault: null

descriptionstring · max: 4096 · nullableOptionalDefault: null

tax_codestring · nullableOptionalDefault: null

activebooleanOptionalDefault: true

Responses

200Success

application/json

A product.

external_idstringRequired

namestring · nullableOptionalDefault: null

descriptionstring · nullableOptionalDefault: null

tax_codestring · nullableOptionalDefault: null

activebooleanRequired

created_atstring · date-timeRequired

400

Validation error, keyed by the failing field.

403

Missing, invalid, or inactive API key.

429

Rate limit exceeded. Carries Retry-After and RateLimit-* headers.

post/products

POST /v1/products HTTP/1.1
Host: api.getsphere.com
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "external_id": "text",
  "name": "text",
  "description": "text",
  "tax_code": "text",
  "active": true
}

{
  "external_id": "text",
  "name": "text",
  "description": "text",
  "tax_code": "text",
  "active": true,
  "created_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a product

get

/products/{external_id}

Base for every public v1 endpoint (products, and customers/transactions later) — named for the surface, not any one resource.

Authorizations

X-API-KEYstringRequired

Path parameters

external_idstringRequired

The external_id you assigned to the record.

Responses

200Success

application/json

A product.

external_idstringRequired

namestring · nullableOptionalDefault: null

descriptionstring · nullableOptionalDefault: null

tax_codestring · nullableOptionalDefault: null

activebooleanRequired

created_atstring · date-timeRequired

403

Missing, invalid, or inactive API key.

404

No record with that external_id.

429

Rate limit exceeded. Carries Retry-After and RateLimit-* headers.

get/products/{external_id}

GET /v1/products/{external_id} HTTP/1.1
Host: api.getsphere.com
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "external_id": "text",
  "name": "text",
  "description": "text",
  "tax_code": "text",
  "active": true,
  "created_at": "2026-01-01T00:00:00.000Z"
}