Sandbox and API keys

Every call is made with an API key and its secret. There are two kinds of key, and the prefix says which world a key belongs to:

Key starts with	Environment	What happens
ck_test_	Sandbox	Real pricing and dispatch, pretend money. Customers are never texted.
ck_live_	Live	Real couriers, real charges.

There is no environment parameter anywhere in the API. The key decides, so sandbox code cannot reach live data by mistake — and quotes, jobs, webhooks and cards made with a sandbox key exist only in the sandbox.

Getting a key

1. Ask us for a merchant account. We set it up with its first user.
2. Sign in to the merchant portal and open Integration. Create a sandbox key.
3. The secret is shown once, when the key is created. Store it in your secret manager.

When you are ready to go live, create a ck_live_ key the same way and swap it in. Nothing else in your code changes.

احتیاط

Treat the secret like a password. Anyone holding a key and its secret can book deliveries on your account. If one leaks, rotate its secret under Integration — the old secret keeps working for a day so you can deploy the new one — or switch the key off, which stops it at once.

Setting up your shell

The examples in these docs read three environment variables:

export COURIER_API="https://api.courier.example"   # the platform’s API address
export COURIER_KEY="ck_test_..."
export COURIER_SECRET="..."

What the sandbox does

• Pricing is real. Quotes come from the same price books as live, so the numbers you see are the numbers you’ll pay.
• Dispatch is real. A sandbox job is offered to sandbox couriers — our test devices, or the courier app pointed at the sandbox. Nothing moves on its own: if no sandbox courier takes a job within 15 minutes, it ends failed, which is itself a path worth testing. Ask us if you’d like a job moved along for you.
• Cards are pretend. Use the sandbox card numbers to make a charge succeed, decline or fail.
• No texts. Customers are never texted the tracking link from the sandbox.
• Webhooks are real. They are signed and retried exactly as in live, to the endpoints you register with your sandbox key.