Requests And Errors

Base address

Every path in the reference starts from:

https://app.adyvance.com/_public/v1

Shop paths start with /orgs/{orgId}/stores/{storeId}. Webhook endpoints and stock adjustments belong to the whole business, so they sit under /orgs/{orgId}. Requests and responses are JSON, in UTF-8. Times are ISO 8601 in UTC, such as 2026-11-05T09:12:44.000Z.

Money

Amounts are whole numbers of paisa (1 rupee = 100 paisa), never decimals:"total_paisa": 420000 is Rs 4,200. Divide by 100 to show rupees. Send prices the same way.

Pages

Lists return one page in data and a next_cursor. Pass it back as cursor to get the next page; when it is null you have everything. Choose the page size with limit (1 to 100). A cursor is opaque: do not build or change one.

# First page
curl "https://app.adyvance.com/_public/v1/orgs/org_…/stores/str_…/products?limit=50" \
  -H "Authorization: Bearer $ADYVANCE_API_KEY"

# Next page: send back next_cursor until it is null
curl "https://app.adyvance.com/_public/v1/orgs/org_…/stores/str_…/products?limit=50&cursor=…" \
  -H "Authorization: Bearer $ADYVANCE_API_KEY"

Retrying safely

Requests that create or move something (making a product, changing an order's status, adjusting stock) need an Idempotency-Key header: a new unique value, such as a UUID, for each change you mean to make.

curl -X POST "https://app.adyvance.com/_public/v1/orgs/org_…/stores/str_…/orders/ord_…/transitions" \
  -H "Authorization: Bearer $ADYVANCE_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-6a51-4c8e-9d0b-1b7f3c2e9a41" \
  -H "Content-Type: application/json" \
  -d '{"to":"confirmed"}'

• If the network fails, send the same request with the same key. If the first one went through, you get its answer back and nothing happens twice.
• Keys are remembered for 24 hours.
• The same key with a different body is refused with 409 idempotency.key_reused.
• If the first request is still running you get 409 idempotency.in_progress; wait a moment and retry.
• If the first request failed, the key is released, so retrying with it is fine.

Editing without overwriting

Orders and products carry a version that goes up with every change. When you edit one, send the version you read in an If-Match header, written as "v3" with the quotes:

curl -X PATCH "https://app.adyvance.com/_public/v1/orgs/org_…/stores/str_…/orders/ord_…" \
  -H "Authorization: Bearer $ADYVANCE_API_KEY" \
  -H 'If-Match: "v3"' \
  -H "Content-Type: application/json" \
  -d '{"note":"Gift wrap, please"}'

If someone changed it in the meantime, for example staff in the admin, you get 412 precondition.version_mismatch and nothing is overwritten. Read it again, apply your change to the new copy, and send it with the new version.

Rate limits

The shop's plan sets how many requests it may make a minute. That allowance is shared by all of the shop's keys and AI apps together, so more keys never means more requests. A key can also have a lower limit of its own (10 to 120 a minute). Every response tells you where you stand:

Over the limit, the answer is 429 rate_limited with a Retry-After header in seconds. Wait that long before trying again, and spread steady work out instead of sending it in bursts.

Errors

A failed request answers with an HTTP error status and this body:

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "validation.invalid",
    "message": "Some fields are not valid.",
    "fields": { "variants.0.price_paisa": "invalid_type" },
    "request_id": "…"
  }
}

• errorobject
  5 fields in error

  • codestring
  • messagestring
  • detailsobject
  • fieldsobject
  • request_idstring

Program against code, which stays stable; the message is for people and may change. Codes have a family before the dot, and the status follows the family:

Versioning

This is version v1 (spec date 2026-10-01). Within v1 we only add: new endpoints, new optional fields and new values. Build your code to ignore fields it does not know. If an endpoint is ever to be removed, its responses first carry Deprecation and Sunset headers, with a Link to the notice.