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 answer422 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
mk_live_…) only on https://mart.ps. The wrong pair answers 401 key_environment_mismatch.
Step 2: Make your first call
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, orinsufficient_scope. See Authenticate and keys.
Step 3: Load towns and products
- A town’s
idis what an order sends asshipping_address.state_id. Match towns onid: names repeat. - Page products until
meta.pagination.has_nextisfalse. Key them onproduct_idandcombination_id, neverreference.
Step 4: Quote a test order
Saveorder.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
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
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
- Ask Mart for a production key (
mk_live_…). - Change the base URL to
https://mart.psand the key, and nothing else. - Check that
X-Mart-Environmentsaysproduction.
partner_reference and Mart removes it.
Next steps
- Sync the catalogue
- Create an order safely
- Handle errors
- The same calls in six languages: Make your first call
