The Merch API is REST over HTTPS, JSON in and JSON out, versioned in the path, and authenticated with a bearer token.
#Base URL
https://api.merch.com
All routes are mounted under /v1, so a full URL looks like:
https://api.merch.com/v1/orders/list
#Versioning
The current version is v1. There is one production deployment. If a future version ever ships, we will publish a deprecation notice with a migration window before retiring v1 — there is no header-based version negotiation today, and no v0 or v2 to pin against.
#Content type
Send Content-Type: application/json on requests with a body. Responses are always JSON unless explicitly noted (the only exception is the 401 Unauthorized plain-text body — see Errors and status codes).
curl -X POST 'https://api.merch.com/v1/contacts/create' \
-H 'Authorization: Bearer <your_api_key>' \
-H 'Content-Type: application/json' \
-d '{ "campaignId": "<id>", "firstName": "Alex", "lastName": "Lee", "email": "[email protected]" }'
#Error shape
Most errors return:
{ "message": "<short reason>" }
400 Bad Request responses for routes with body validation also include an errors array of issue messages from the validator:
{
"message": "Invalid request body",
"errors": ["shipTo.email: Invalid email", "products: Array must contain at least 1 element(s)"]
}
401 Unauthorized is the one exception — it returns plain text Unauthorized, not JSON. Code your client to read message from JSON responses and to fall back to the raw body on 401.
For the full breakdown, see Errors and status codes.
#Common status codes
| Code | Meaning |
| --- | --- |
| 200 OK | Successful read or update. |
| 201 Created | Successful create. Some routes also return 201 on cancel — read the per-resource article. |
| 400 Bad Request | Validation failed, malformed body, or the operation isn't allowed in the current state. |
| 401 Unauthorized | Missing, malformed, or invalid API key. Plain-text body. |
| 404 Not Found | The resource id wasn't found. Currently emitted only by GET /v1/orders/{orderId}. |
| 429 Too Many Requests | You've exceeded the rate limit. |
| 500 Internal Server Error | Something went wrong on our side. Safe to retry idempotent reads; see notes in Errors and status codes before retrying writes. |
#Pagination
Pagination conventions differ by resource. Read the per-resource article for the parameters that endpoint accepts.
Orders, products, and contacts use offset pagination:
| Param | Default |
| --- | --- |
| limit | 20 |
| offset | 0 |
curl -X GET 'https://api.merch.com/v1/orders/list?limit=50&offset=100' \
-H 'Authorization: Bearer <your_api_key>'
Inventory uses page pagination — note the different parameter names:
| Param | Default | Max |
| --- | --- | --- |
| page | 1 | — |
| page_size | 20 | 100 |
curl -X GET 'https://api.merch.com/v1/inventory/list?page=2&page_size=50' \
-H 'Authorization: Bearer <your_api_key>'
The inventory response includes a pagination object with total_count, page, page_size, and has_more. Other list endpoints return a JSON array directly.
#Field naming
Most resources use camelCase keys (orderNumber, firstName, trackingNumber). Inventory is the exception — it returns snake_case (product_name, on_hand, inventory_events). The per-resource articles call this out where it matters; don't normalize keys silently in your client.
#Next
- Authentication and API keys for the
Authorizationheader contract. - Rate limits for the per-IP request budget and headers you'll see on every response.
- Errors and status codes for full handling guidance.