UnifyCart Developers

Your First Request

From nothing to a working call in five minutes, and what to check when it does not work.

1. Get a Token

The merchant issues it in their admin: Settings, API Tokens. Ask them for the abilities you actually need, named for your system so they can revoke yours without breaking anything else.

The token is shown once. If it is lost, they issue another.

2. Find the Shop's Address

Every shop has its own domain, and the API lives on it. There is no central endpoint.

https://shop.example.com/api/v1/...

3. Make a Call

curl -s https://shop.example.com/api/v1/products \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

You should get a paginated list of active products.

4. Read One

curl -s https://shop.example.com/api/v1/products/premium-laptop \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Either an id or a slug works.

When It Does Not Work

401 Unauthenticated. No token reached us. Check the header is Authorization: Bearer ... and that your client is not stripping it on a redirect, which is a common cause when the shop redirects from the bare domain to www or the other way.

401 Invalid or expired token. The token is wrong, revoked, or past its expiry. Ask the merchant to confirm it still exists.

403 Insufficient permissions. The token is valid and lacks the ability for this endpoint. Retrying will not help; ask for the ability.

404 on a product you can see in the admin. Only active products are returned. A draft is invisible to the API.

HTML instead of JSON. You are probably hitting the storefront rather than the API, usually a missing /api/v1 or a redirect. Send Accept: application/json so errors come back as JSON rather than an error page.

5. Create Something

If your token carries write_orders, place a test order and then look at it in the merchant's admin.

curl -s -X POST https://shop.example.com/api/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "customer_id": 1,
    "customer_email": "test@example.com",
    "customer_name": "Test Buyer",
    "items": [{ "product_id": 1, "qty": 1 }]
  }'

That is a real order

It takes stock, emails the customer address you gave, and appears in the merchant's figures. There is no test mode. Do this on a shop you are allowed to put rubbish into, and cancel the order afterwards so the stock goes back.

The Full Reference

Each shop publishes a complete, generated reference at /docs/api on its own domain. It is produced from the code, so it describes the behaviour rather than an intention.

Use these pages for how things fit together and that reference for exact fields.

Errors and Conventions before you write any parsing, particularly the part about money being a string.

Then the endpoint you need, and Webhooks if you want to know when something happens rather than asking.