# Acme Commerce API

> Everything you need to sell: customers, orders, refunds, the product catalogue and webhooks. REST over HTTPS, JSON in and out, bearer-token authenticated.

All endpoints are relative to `https://api.acme.example`.

## API versions

| Version | Status | Endpoints |
| --- | --- | --- |
| `v2` | current | 15 |
| `v1` | deprecated — retires 2026-09-01 | 9 |

Write new integrations against `v2`. Every endpoint below states the version it belongs to, and any endpoint with a newer edition links to it.

## Getting started

- [Introduction](/pages/introduction.md): 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](/pages/use-cases.md): Three things teams build with the Acme Commerce API, in the order people usually build them.
- [Versioning](/pages/versioning.md): This API serves 2 versions at once. The version is part of the path, so a request names the version it wants.
- [Authentication](/pages/authentication.md): Authenticated endpoints expect a bearer token.
- [Errors](/pages/errors.md): Errors are returned with a conventional HTTP status and a JSON body.
- [Rate limiting](/pages/rate-limiting.md): Requests are rate limited per client. Exceeding a limit returns 429 Too Many Requests.

## Guides

- [Pagination](/pages/pagination.md): 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](/endpoints/v2-auth-tokens-store.md): Issue an access token
- [DELETE /api/v2/auth/tokens/current](/endpoints/v2-auth-tokens-destroy.md): Revoke the current token

## Customers (v2)

Create and manage the people who place orders.

- [GET /api/v2/customers](/endpoints/v2-customers-index.md): List customers
- [POST /api/v2/customers](/endpoints/v2-customers-store.md): Create a customer
- [GET /api/v2/customers/{customer}](/endpoints/v2-customers-show.md): Retrieve a customer
- [PATCH /api/v2/customers/{customer}](/endpoints/v2-customers-update.md): Update a customer
- [DELETE /api/v2/customers/{customer}](/endpoints/v2-customers-destroy.md): Delete a customer

## Orders (v2)

Place, read and refund orders.

- [GET /api/v2/orders](/endpoints/v2-orders-index.md): List orders
- [POST /api/v2/orders](/endpoints/v2-orders-store.md): Create an order
- [GET /api/v2/orders/{order}](/endpoints/v2-orders-show.md): Retrieve an order
- [POST /api/v2/orders/{order}/refunds](/endpoints/v2-orders-refunds-store.md): Refund an order

## Products (v2)

The public product catalogue.

- [GET /api/v2/products](/endpoints/v2-products-index.md): List products
- [GET /api/v2/products/{product}](/endpoints/v2-products-show.md): Retrieve a product

## Webhooks (v2)

Receive signed callbacks when things happen in your account.

- [GET /api/v2/webhooks](/endpoints/v2-webhooks-index.md): List webhook endpoints
- [POST /api/v2/webhooks](/endpoints/v2-webhooks-store.md): Register a webhook endpoint

## Authentication (v1)

Unchanged in v2 apart from the path.

- [POST /api/v1/auth/tokens](/endpoints/v1-auth-tokens-store.md): Issue an access token
- [DELETE /api/v1/auth/tokens/current](/endpoints/v1-auth-tokens-destroy.md): Revoke the current token

## Customers (v1)

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

- [GET /api/v1/customers](/endpoints/v1-customers-index.md): List customers
- [POST /api/v1/customers](/endpoints/v1-customers-store.md): Create a customer
- [GET /api/v1/customers/{customer}](/endpoints/v1-customers-show.md): Retrieve a customer

## Orders (v1)

Placing and reading orders. Refunds arrived in v2.

- [GET /api/v1/orders](/endpoints/v1-orders-index.md): List orders
- [POST /api/v1/orders](/endpoints/v1-orders-store.md): Create an order

## Products (v1)

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

- [GET /api/v1/products](/endpoints/v1-products-index.md): List products
- [GET /api/v1/products/search](/endpoints/v1-products-search.md): Search products

## Machine-readable

- [OpenAPI 3.1](/openapi.json): complete machine-readable specification.
- [Full text](/llms-full.txt): every endpoint in one file.
- [Discovery](/.well-known/api-docs): index of every documentation surface.