Developers
Requests & errors
What every endpoint has in common: how IDs, money and dates are written, how lists page, how to make changes safely, the limits, and the errors.
JSON
Requests and answers are JSON, with camelCase field names. Send Content-Type: application/json with a body. Answers can gain fields at any time, so ignore the ones you don't know.
IDs
Everything that comes from Shopify has two IDs: id, the number in Shopify admin URLs, as a string, and gid, Shopify's global ID. Paths and parameters take either, so you can use whichever you have, such as the one in a Shopify webhook. Subscription lines are the exception: they have only a gid, in id.
| Field | Type | Description |
|---|---|---|
id | string | The numeric id, the one in Shopify admin URLs. |
gid | string | Shopify's global id. |
Money
Amounts are strings with the currency's own number of decimal places, never numbers, so they can't lose a cent to rounding.
| Field | Type | Description |
|---|---|---|
amount | string | A decimal string with the currency's own number of decimals: "12.50", "1086" for yen. Never a float. |
currencyCode | string |
{
"amount": "12.50",
"currencyCode": "USD"
}Dates and time zones
Times are ISO 8601 with an offset, such as 2026-11-14T16:00:00Z. Dates without a time, such as a next order's nextBilling.date, are YYYY-MM-DD in your store's time zone, which /v1/shop answers as timeZone. That's the zone set in Vanix under Settings → Time zone.
Lists and pages
Lists take limit, from 1 to 100 (25 if you leave it out), and answer a page:
{
"data": [
{ "id": "26893631718", … }
],
"nextCursor": "eyJvIjoyNX0"
}To read the next page, send nextCursor back as cursor, with the same other parameters. On the last page, nextCursor is null. Treat cursors as opaque: their contents can change.
Activity lists can answer a page with fewer events than limit, or none, and still have more. Keep following nextCursor until it's null.
Previews and revisions
Every subscription has a revisionId, which changes whenever the subscription does. A change that's priced (a swap, an add, removing an item, a cancel, an address, a discount code) takes two calls:
- The preview, such as
POST /v1/subscriptions/{id}/swap/preview. It prices the change, writes nothing, and answers therevisionIdit priced against. - The change, such as
POST /v1/subscriptions/{id}/swap, with thatrevisionId.
If the subscription changed in between, because the customer or your staff edited it, the change is refused with 409 revision_conflict, and the error's currentRevisionId is the one to preview against again. This is so a price you checked is never charged against a different subscription.
The other changes (quantities, pause, resume, skip, reschedule, frequency, ship now) take a revisionId but don't need one. Send it when you want the change refused if anything has moved since you read the subscription.
Retrying safely
If a request times out, you can't tell whether it was made. Send an Idempotency-Key header with changes, any string up to 255 characters that's unique to that change, such as a UUID, and send the same one when you retry:
- A repeat within 24 hours gets the first answer back, with the header
Idempotent-Replayed: true, and doesn't make the change again. - The same key with a different request is refused with
422 idempotency_key_reused. - A repeat while the first is still running is refused with
409 request_in_progress. Wait and try again.
Use one on ship now and add above all. Retrying them without one could charge a customer, or add an item, twice.
Customer emails
Changes that can email the customer take notifyCustomer, which is false unless you send true, as in Vanix. The answer's notification.sent says whether an email went. The email is the same one your staff's change would send, from your customer emails.
Rate limits
Each store can make 4 requests a second, with bursts of up to 40, shared by all its keys. Each key can use half of that, 2 a second with bursts of up to 20, so one busy integration can't hold up the rest. The limits are the same on every plan.
Every answer says where you stand, for whichever is closer to running out:
| Header | Means |
|---|---|
X-RateLimit-Limit | The most requests you can make at once. |
X-RateLimit-Remaining | How many you can make right now. |
X-RateLimit-Reset | Seconds until you're back to the limit. |
Over the limit, a request is refused with 429 rate_limited. Its scope is shop or key, for which limit you reached, and the Retry-After header says how many seconds to wait.
Shopify limits Vanix too. If Shopify asks us to slow down while answering you, the answer is 503 shopify_throttled with a Retry-After. Wait that long and retry.
Your Vanix plan
The API follows your Vanix plan, like Vanix itself:
- With no plan, every request is refused with
402 app_plan_required. - While changes in Vanix are paused, because your plan has ended or you've been over your limit for 30 days, reads still work, and changes are refused with
403 app_plan_endedor403 app_plan_locked. These still work: read it again from Shopify, pause, cancel and every preview.
Errors
Every error has the same shape:
{
"error": {
"type": "conflict",
"code": "revision_conflict",
"message": "This subscription has changed",
"currentRevisionId": "860896133351",
"requestId": "req_9f1c0b2e4d5a4e7f8a6b3c2d1e0f9a8b"
}
}| Field | Means |
|---|---|
type | The kind of error: invalid_request (400, 413 or 422), unauthenticated (401), plan (402, or 403 for a plan), forbidden (403), not_found (404), conflict (409), rate_limited (429), upstream (502 to 504, when Shopify fails) or internal (500). |
code | What went wrong, from the list below. It never changes for the same error, so write your code against it. |
message | An explanation in English, for a developer. It can change, so don't match on it. |
param | The request field at fault, when there is one. |
requestId | The request's ID, also sent as the Request-Id header on every answer. Quote it if you contact us about a request. |
Some errors add fields, such as requiredScope, scope, planSelectionUrl or currentRevisionId. An answer of 500 internal_error is a fault on our side. Retrying it is safe with an Idempotency-Key.
Every request is answered within 60 seconds.
Errors any request can get
Any request can be refused for its key, its rate, or your plan, and can fail when Shopify does. Each endpoint's reference lists the other codes it can answer with.
| Code | Status | Meaning |
|---|---|---|
key_in_query | 400 | A key in the URL. Send it in the header only; URLs are logged. |
invalid_api_key | 401 | Not a key we know, or one that has been revoked. |
missing_api_key | 401 | No Authorization: Bearer header, or not a key. |
wrong_environment | 401 | A vx_test_ key on the live API, or the reverse. |
app_plan_required | 402 | The store has no Vanix plan; planSelectionUrl is where to choose one. |
api_access_suspended | 403 | API access for the store is paused by us. Contact hello@vanixcommerce.com. |
not_found | 404 | No such endpoint, or nothing at this path. |
rate_limited | 429 | Too many requests; scope says whether the store or this key is over, and Retry-After when to try again. |
internal_error | 500 | Our fault. Quote the requestId. |
shopify_error | 502 | Shopify refused or failed the change. |
shopify_connection_lost | 503 | Shopify no longer accepts the app's access for this store; the merchant needs to open the app to reconnect it. |
shopify_throttled | 503 | Shopify is throttling this store's requests. Retry after Retry-After. |
shopify_unavailable | 503 | Shopify could not be reached. |
unavailable | 503 | We could not check the key just now. Retry shortly. |
shopify_timeout | 504 | Shopify took too long to answer. |
Every other error code
| Code | Status | Meaning |
|---|---|---|
country_required | 400 | The address needs a country. |
discount_code_required | 400 | No code was sent. |
invalid_date | 400 | Not a valid date. |
invalid_frequency | 400 | Not a frequency. |
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
invalid_idempotency_key | 400 | Idempotency-Key is empty or longer than 255 characters. |
invalid_json | 400 | The body is not valid JSON. |
invalid_kind | 400 | Choose whether the item renews or is for the next order only. |
invalid_pagination | 400 | limit is not 1 to 100, or cursor is not one this API returned. |
invalid_price | 400 | A price is missing, negative or too large. |
invalid_quantity | 400 | Quantity must be a whole number in the allowed range. |
invalid_reason | 400 | reasonId or childId is not one of the store's cancellation reasons. |
invalid_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
invalid_status | 400 | status is not a subscription status. |
invalid_variant_id | 400 | Not a product variant id. |
invalid_when | 400 | when must be immediate or endOfCycle. |
line_id_required | 400 | The line to change is missing. |
revision_id_required | 400 | This change is priced, so it needs the revisionId the price was given at. |
app_plan_ended | 403 | The store's plan has ended. Reads work; changes other than cancel, pause, sync and previews are refused. |
app_plan_locked | 403 | The store is over its plan's limit past the grace period. Reads work; changes other than cancel, pause, sync and previews are refused. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
customer_not_found | 404 | No customer with that id in this store. |
discount_not_found | 404 | No such discount on this subscription. |
line_not_found | 404 | No line with that id on this subscription. |
subscription_not_found | 404 | No subscription with that id in this store. |
cancellation_not_scheduled | 409 | The subscription is not set to end. |
cancellation_scheduled | 409 | The subscription is already set to end. |
charge_in_progress | 409 | An order for this subscription is being charged now. Retry in a minute. |
charging_disabled | 409 | Charging is turned off, so nothing would be shipped. |
conflict | 409 | The request conflicts with the state of the subscription; message says how. |
delivery_option_unavailable | 409 | The delivery option chosen is no longer offered for that address. Preview again. |
discount_already_applied | 409 | The code is already on this subscription. |
discount_does_not_combine | 409 | The code does not combine with a discount already on the subscription. |
discount_running | 409 | A cancellation discount is running; change the frequency once it ends. |
frequency_not_offered | 409 | That frequency is not offered for everything on the subscription. |
payment_recovering | 409 | A failed payment is being retried. |
request_in_progress | 409 | A request with this Idempotency-Key is still running. |
revision_conflict | 409 | The subscription has changed since revisionId. Read it, or preview again, and retry. |
same_frequency | 409 | The subscription already has that frequency. |
schedule_changed | 409 | The date of the order changed. Read the subscription and retry. |
subscription_not_active | 409 | Only an active subscription can do this. |
subscription_not_paused | 409 | The subscription is not paused. |
body_too_large | 413 | The body is too large. |
country_not_shipped | 422 | The store does not ship to that country. |
date_in_past | 422 | The new date is not in the future. To charge now, use ship-now. |
discount_code_not_found | 422 | No discount with that code, or it has been deleted. |
discount_currency_mismatch | 422 | A fixed-amount code in another currency than the subscription's. |
discount_expired | 422 | The code has expired. |
discount_minimum_not_met | 422 | The subscription does not meet the code's minimum. |
discount_no_eligible_lines | 422 | Nothing on the subscription is covered by the code. |
discount_not_applicable | 422 | The code cannot be applied to this subscription. |
discount_not_started | 422 | The code has not started yet. |
discount_used_up | 422 | The code has reached its usage limit. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
last_line | 422 | The subscription's last line cannot be removed; cancel instead. |
no_billing_interval | 422 | The subscription has no billing interval to resume on. |
no_delivery_rates | 422 | Shopify has no delivery rates for that address. |
no_upcoming_order | 422 | The subscription has no upcoming order. |
not_shipped | 422 | The subscription is picked up or delivered locally, so it has no shipping address to change. |
payment_update_not_sendable | 422 | The email cannot be sent: no address, a suppressed address, or a payment method Shopify cannot send a link for. |
prepaid_subscription | 422 | Not possible on a prepaid subscription. |
product_unavailable | 422 | The product is deleted or not active. |
same_variant | 422 | That variant is already on this line. |
subscription_closed | 422 | The subscription is cancelled or expired. |
subscription_paused | 422 | The subscription is paused; resume it first. |
too_many_lines | 422 | The subscription has as many lines as it can hold. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
payment_update_recently_sent | 429 | An update email was sent moments ago. Try again in a few minutes. |