Dropship API setup and sandbox

Use the private test token from your approved dropship account. The base URL is:

https://affiliates.keepkey.com/api/dropship/v1

Send Authorization: Bearer <token> on requests and Content-Type: application/json for order creation. This is REST over HTTPS, separate from the affiliate MCP endpoint. Keep the token in backend secret storage, outside browser bundles and source control.

Read the catalog

From a private development terminal with KEEPKEY_DROPSHIP_TEST_TOKEN already set:

curl --fail-with-body \
  'https://affiliates.keepkey.com/api/dropship/v1/products' \
  -H "Authorization: Bearer ${KEEPKEY_DROPSHIP_TEST_TOKEN}"

Read the returned sku, price, currency, availability and shippingRegions. The current real SKU is KK-HW-001, priced at $49 USD per unit with US-only destinations. The catalog is the place to recheck those values before taking orders. This is a fulfillment price, not a retail-margin promise or a live inventory guarantee.

Prepare a sandbox order

Create an order.json containing fictional customer data:

{
  "externalOrderId": "sandbox-order-001",
  "customerName": "Example Customer",
  "customerEmail": "customer@example.com",
  "shippingAddress": {
    "line1": "123 Example Street",
    "city": "Boston",
    "state": "MA",
    "postalCode": "02110",
    "country": "US"
  },
  "lineItems": [{ "sku": "KK-TEST-001", "quantity": 1 }],
  "shippingMethod": "standard"
}

externalOrderId is your stable storefront order reference. The address requires a two-letter country code; quantities must be positive integers. line2 and notes are optional. The reserved test SKU never ships.

curl --fail-with-body \
  'https://affiliates.keepkey.com/api/dropship/v1/orders' \
  -H "Authorization: Bearer ${KEEPKEY_DROPSHIP_TEST_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data-binary @order.json

Verify the result and retry behavior

Check that the response includes a keepKeyOrderId, sandbox: true and settlement: null. Sandbox mode stores a test order without drawing fulfillment credit, allocating a settlement or sending an order to Shopify.

Store the returned KeepKey ID with your external ID. Send the same external ID with an identical payload to rehearse a retry: it returns the existing order. Reusing that ID with changed details returns HTTP 409, duplicate_external_order_id. Do not create a new ID automatically after a timeout; look up the original order first.

A passing sandbox test is one integration check. Moving to the live token creates real operational obligations; follow Forward and track orders, Settlements and Webhook verification before enabling it.