API quick start

This guide takes you from nothing to a test order in about 15 minutes. Everything here uses a test key: test orders are priced exactly like real ones but are never charged, made or shipped.

Base URL: https://www.promogator.com/api/on-demand/v1

All requests and responses are JSON over HTTPS. Money is a string with two decimals ("16.95"), times are UTC (2026-10-18T09:30:00Z).

#Step 1: Create a test key

In your partner portal open On Demand → Developers → API keys and create a key. Tick the scopes you need:

You get an Access Key ID (pgod_test_ak_…) and a Secret Key (pgod_test_sk_…). The Secret Key is shown once: store it in your server's secret store, never in a browser, an app or a code repository.

#Step 2: Get an access token

Exchange the key for an access token. Send the Access Key ID and Secret Key with HTTP Basic authentication:

curl -X POST https://www.promogator.com/api/on-demand/v1/oauth/token \
  -u "pgod_test_ak_XXXXXXXX:pgod_test_sk_XXXXXXXX" \
  -d grant_type=client_credentials

{
  "access_token": "pgod_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "catalog:read orders:read orders:write"
}

The token lasts 60 minutes. Keep it and reuse it until it expires; do not request a new token for every call. Send it on every other request:

export TOKEN="pgod_at_…"

#Step 3: Read your catalog

curl https://www.promogator.com/api/on-demand/v1/catalog/products \
  -H "Authorization: Bearer $TOKEN"

You get a list of your products. Fetch one product to see every variant (colour and size) with its SKUs and your NET price:

curl https://www.promogator.com/api/on-demand/v1/catalog/products/odp_01JABC… \
  -H "Authorization: Bearer $TOKEN"

Each variant has an od_sku (ours) and, for your own designs, a partner_sku (yours). You can order with either.

#Step 4: Price an order (optional)

A quote prices an order without placing it: items, shipping, tax and total.

curl -X POST https://www.promogator.com/api/on-demand/v1/quotes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "name": "Alex Rivera",
      "address1": "123 Main Street",
      "city": "Boise", "state": "ID", "postal_code": "83702"
    },
    "items": [ { "partner_sku": "ST-WILD-SPT-BLK-L", "quantity": 1, "retail_price": "35.00" } ]
  }'

#Step 5: Place a test order

Every new order needs an Idempotency-Key header: a unique value you choose for this order, such as your store's order ID. If your request times out, send it again with the same key and you will never create a second order.

curl -X POST https://www.promogator.com/api/on-demand/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1203" \
  -d '{
    "external_id": "1203",
    "recipient": {
      "name": "Alex Rivera",
      "address1": "123 Main Street",
      "city": "Boise", "state": "ID", "postal_code": "83702"
    },
    "items": [ { "partner_sku": "ST-WILD-SPT-BLK-L", "quantity": 1, "retail_price": "35.00" } ],
    "metadata": { "store_order_id": "5512" }
  }'

The response is the order (201 Created), with an id like test_odo_…, the items at your NET price, shipping, tax and the total. external_id is your order number; you can look the order up by it later:

curl https://www.promogator.com/api/on-demand/v1/orders/by-external-id/1203 \
  -H "Authorization: Bearer $TOKEN"

#Step 6: Get tracking back

Two ways:

• Webhooks (recommended): add an endpoint and we send order.shipped with the carrier and tracking number as soon as a package ships. See Webhooks.
• Polling: GET /orders/{id}/shipments.

#Next

• Test mode and going live: the checklist and how to get your live key.
• Endpoints: every call, with its fields.
• Errors, limits and idempotency: what can go wrong and how to handle it.