Make your first API call

Updated May 29, 20261 min read

The Carriyo API uses OAuth 2.0 client credentials. Every request needs an access token. Get one by exchanging the client ID and secret you created in Get API credentials.

Step 1, request an access token

Send your client_id and client_secret to the OAuth endpoint to receive an access token. Use that token as a bearer in the Authorization header of every subsequent API request.

Cache your access token

Cache the access token client-side until it expires. Don't request a new token for every API call. That creates unnecessary load and slows your integration down.

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET and run:

curl --location --request POST 'https://api.carriyo.com/oauth/token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

The response contains your access_token and its lifetime.

Step 2, create your first shipment

With the access token in hand, you can call any Carriyo endpoint. Here is a minimal create shipment request. Replace these values:

YOUR_TENANT_ID
YOUR_MERCHANT_ID
YOUR_API_KEY
YOUR_ACCESS_TOKEN

curl --location --request POST 'https://api.carriyo.com/shipments?draft=true' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'tenant-id: YOUR_TENANT_ID' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data-raw '{
    "merchant": "YOUR_MERCHANT_ID",
    "references": {
      "partner_order_reference": "YOUR_ORDER_REF",
      "partner_shipment_reference": "YOUR_ORDER_REF-1"
    },
    "payment": {
      "total_amount": 100.0,
      "currency": "USD"
    },
    "items": [
      {
        "description": "Awesome t-shirt",
        "quantity": 1,
        "price": { "amount": 100.0, "currency": "USD" },
        "sku": "S12345"
      }
    ],
    "dropoff": {
      "contact_name": "Joe Bloggs",
      "contact_phone": "+18005550123",
      "contact_email": "customer@example.com",
      "address1": "1234 Elm Street",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postcode": "94103",
      "coords": [37.7749, -122.4194]
    }
  }'

Try it in the browser

Prefer not to copy-paste cURL? You can also create your first shipment via the interactive console on the Create shipment API page.

The ?draft=true query parameter creates the shipment without booking with a carrier, useful while you're testing. Drop it (or set draft=false) to actually book.