# Dropship API setup and sandbox

import StepVideo from '@/components/StepVideo'

# Dropship API setup and sandbox

<StepVideo id="aff-11-dropship-sandbox" />

Use the private **test token** from your [approved dropship account](/docs/dropshipping/getting-started). The base URL is:

```text
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:

```bash
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:

```json
{
  "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.

```bash
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](/docs/dropshipping/orders#look-up-an-order) first.

A passing sandbox test is one integration check. Moving to the live token creates real operational obligations; follow [Forward and track orders](/docs/dropshipping/orders), [Settlements](/docs/dropshipping/settlements) and [Webhook verification](/docs/dropshipping/webhooks) before enabling it.