Acme Commerce API

Getting started

• Introduction Everything you need to sell: customers, orders, refunds, the product catalogue and webhooks. REST over HTTPS, JSON in and out, bearer-token authenticated.
• Use cases Three things teams build with the Acme Commerce API, in the order people usually build them.
• Versioning This API serves 2 versions at once. The version is part of the path, so a request names the version it wants.
• Authentication Authenticated endpoints expect a bearer token.
• Errors Errors are returned with a conventional HTTP status and a JSON body.
• Rate limiting Requests are rate limited per client. Exceeding a limit returns 429 Too Many Requests.

Guides

• Pagination Every list endpoint pages the same way, so this is documented once here rather than repeated on each one.

Authentication (v2)

Exchange an API key pair for a bearer token, and revoke it when you are done.

• POST /api/v2/auth/tokens Issue an access token
• DELETE /api/v2/auth/tokens/current Revoke the current token

Customers (v2)

Create and manage the people who place orders.

• GET /api/v2/customers List customers
• POST /api/v2/customers Create a customer
• GET /api/v2/customers/{customer} Retrieve a customer
• PATCH /api/v2/customers/{customer} Update a customer
• DELETE /api/v2/customers/{customer} Delete a customer

Orders (v2)

Place, read and refund orders.

• GET /api/v2/orders List orders
• POST /api/v2/orders Create an order
• GET /api/v2/orders/{order} Retrieve an order
• POST /api/v2/orders/{order}/refunds Refund an order

Products (v2)

The public product catalogue.

• GET /api/v2/products List products
• GET /api/v2/products/{product} Retrieve a product

Webhooks (v2)

Receive signed callbacks when things happen in your account.

• GET /api/v2/webhooks List webhook endpoints
• POST /api/v2/webhooks Register a webhook endpoint

Authentication (v1)

Unchanged in v2 apart from the path.

• POST /api/v1/auth/tokens Issue an access token Deprecated
• DELETE /api/v1/auth/tokens/current Revoke the current token Deprecated

Customers (v1)

Reading and creating customers. Updating and deleting them arrived in v2.

• GET /api/v1/customers List customers Deprecated
• POST /api/v1/customers Create a customer Deprecated
• GET /api/v1/customers/{customer} Retrieve a customer Deprecated

Orders (v1)

Placing and reading orders. Refunds arrived in v2.

• GET /api/v1/orders List orders Deprecated
• POST /api/v1/orders Create an order Deprecated

Products (v1)

The public product catalogue, with the search route v2 replaced.

• GET /api/v1/products List products Deprecated
• GET /api/v1/products/search Search products Deprecated