> For the complete documentation index, see [llms.txt](https://docs.getsphere.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getsphere.com/features/integrations/api/transaction-api/products.md).

# 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

> 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.

```json
{"openapi":"3.1.0","info":{"title":"Sphere API","version":"1.0.0"},"servers":[{"url":"https://api.getsphere.com/v1"},{"url":"https://server.getsphere.com/tax_api/v1"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"CreateProductRequest":{"additionalProperties":false,"description":"Body for ``POST /v1/products``.\n\n``external_id`` is the caller's own product identifier and doubles as the\nnatural idempotency key: re-posting the same ``external_id`` updates the\nexisting product (merge — only the fields you send change).","properties":{"external_id":{"maxLength":255,"minLength":1,"title":"External Id","type":"string"},"name":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"description":{"anyOf":[{"maxLength":4096,"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"tax_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tax Code"},"active":{"default":true,"title":"Active","type":"boolean"}},"required":["external_id"],"title":"CreateProductRequest","type":"object"},"ProductResponse":{"description":"A product.","properties":{"external_id":{"title":"External Id","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"tax_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tax Code"},"active":{"title":"Active","type":"boolean"},"created_at":{"format":"date-time","title":"Created At","type":"string"}},"required":["external_id","active","created_at"],"title":"ProductResponse","type":"object"}}},"paths":{"/products":{"post":{"operationId":"products_create","description":"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.","summary":"Create or update a product","tags":["Products"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CreateProductRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateProductRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}},"description":""},"400":{"description":"Validation error, keyed by the failing field."},"403":{"description":"Missing, invalid, or inactive API key."},"429":{"description":"Rate limit exceeded. Carries Retry-After and RateLimit-* headers."}}}}}}
```

## GET /products/{external\_id}

> Retrieve a product

```json
{"openapi":"3.1.0","info":{"title":"Sphere API","version":"1.0.0"},"servers":[{"url":"https://api.getsphere.com/v1"},{"url":"https://server.getsphere.com/tax_api/v1"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ProductResponse":{"description":"A product.","properties":{"external_id":{"title":"External Id","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"tax_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tax Code"},"active":{"title":"Active","type":"boolean"},"created_at":{"format":"date-time","title":"Created At","type":"string"}},"required":["external_id","active","created_at"],"title":"ProductResponse","type":"object"}}},"paths":{"/products/{external_id}":{"get":{"operationId":"products_retrieve","summary":"Retrieve a product","parameters":[{"in":"path","name":"external_id","schema":{"type":"string"},"description":"The external_id you assigned to the record.","required":true}],"tags":["Products"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}},"description":""},"403":{"description":"Missing, invalid, or inactive API key."},"404":{"description":"No record with that external_id."},"429":{"description":"Rate limit exceeded. Carries Retry-After and RateLimit-* headers."}}}}}}
```