Skip to main content
Build against the sandbox, https://sandbox.mart.ps: the same API, where nothing is delivered or charged. Mart issues a production key once your integration passes the test order in steps 5 and 6.

Prerequisites

  • A sandbox key (mk_test_…) from Mart, with order creation enabled. Until it is, order calls answer 422 orders_not_enabled; catalogue reads still work.
  • The sandbox fixture list Mart sends with it: products, towns and codes prepared for testing.
  • A server-side place for the key, such as an environment variable. Never put a key in client-side code, an app, a repository or a URL.

Step 1: Set the base URL and key

A sandbox key works only on the sandbox, and a production key (mk_live_…) only on https://mart.ps. The wrong pair answers 401 key_environment_mismatch.

Step 2: Make your first call

A 200 means the key works. Check the X-Mart-Environment header (sandbox or production) once at startup, so a wrong base URL fails on the first call, not the first order.
  • 401: the key is missing, wrong, paused, revoked or for the other environment. Do not retry; fix it.
  • 403: the account is not permitted right now, or insufficient_scope. See Authenticate and keys.

Step 3: Load towns and products

  • A town’s id is what an order sends as shipping_address.state_id. Match towns on id: names repeat.
  • Page products until meta.pagination.has_next is false. Key them on product_id and combination_id, never reference.

Step 4: Quote a test order

Save order.json with a fixture product and a town id:
order.json
data.validation.quote gives the totals, the delivery fee and your reward. Nothing is created.

Step 5: Create the order twice

Expect 201 with meta.idempotency_replay: false. Send the exact same request again: expect 200, meta.idempotency_replay: true and the same order id. This is how a retry after a timeout stays safe.

Step 6: Cancel it twice

Expect 200 with already_cancelled: false, then already_cancelled: true the second time.

How does the sandbox differ?

Rate limits, error codes, the envelope and idempotency are the same as production.

Go live

  1. Ask Mart for a production key (mk_live_…).
  2. Change the base URL to https://mart.ps and the key, and nothing else.
  3. Check that X-Mart-Environment says production.
If you place one real order as a final check, tell Mart its partner_reference and Mart removes it.

Next steps