Before you begin

You need an API key. If you don't have one yet, follow the Quickstart and export it:

export API_KEY="paste-your-key-here"

Anatomy of a request

Every request has the same four parts:

curl "https://api.example.com/v1/orders?limit=1" \
  -X GET \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json"
PartWhat it does
URLThe endpoint, including the version prefix /v1
MethodGET to read data, POST to create it
Authorization headerYour credential, so the API knows who is calling
Query or bodyFilters and data, depending on the endpoint

Read data

Fetch your most recent order:

curl "https://api.example.com/v1/orders?limit=1" \
  -H "Authorization: Bearer $API_KEY"

A successful call returns 200 OK:

{
  "data": [
    {
      "id": "ord_1042",
      "status": "shipped",
      "total": 129.00
    }
  ],
  "has_more": false
}

Write data

Create a resource with a POST request and a JSON body:

curl "https://api.example.com/v1/orders" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"total": 42.50, "currency": "USD"}'

A successful create returns 201 Created and the new resource, including its id.

Check the response

StatusMeaningWhat to do
200 OKThe request succeeded.Read the JSON body.
201 CreatedA resource was created.Save the id for later calls.
401 UnauthorizedThe key is missing, revoked, or mistyped.Check the Authorization header.
422 Unprocessable EntityThe body failed validation.Read the error field, fix the request.
429 Too Many RequestsYou're over your rate limit.Back off and retry. See Rate limits.

Next steps