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.

FieldTypeDescription
idstringThe numeric id, the one in Shopify admin URLs.
gidstringShopify'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.

FieldTypeDescription
amountstringA decimal string with the currency's own number of decimals: "12.50", "1086" for yen. Never a float.
currencyCodestring
{
  "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:

  1. The preview, such as POST /v1/subscriptions/{id}/swap/preview. It prices the change, writes nothing, and answers the revisionId it priced against.
  2. The change, such as POST /v1/subscriptions/{id}/swap, with that revisionId.

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:

HeaderMeans
X-RateLimit-LimitThe most requests you can make at once.
X-RateLimit-RemainingHow many you can make right now.
X-RateLimit-ResetSeconds 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_ended or 403 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"
  }
}
FieldMeans
typeThe 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).
codeWhat went wrong, from the list below. It never changes for the same error, so write your code against it.
messageAn explanation in English, for a developer. It can change, so don't match on it.
paramThe request field at fault, when there is one.
requestIdThe 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.

CodeStatusMeaning
key_in_query400A key in the URL. Send it in the header only; URLs are logged.
invalid_api_key401Not a key we know, or one that has been revoked.
missing_api_key401No Authorization: Bearer header, or not a key.
wrong_environment401A vx_test_ key on the live API, or the reverse.
app_plan_required402The store has no Vanix plan; planSelectionUrl is where to choose one.
api_access_suspended403API access for the store is paused by us. Contact hello@vanixcommerce.com.
not_found404No such endpoint, or nothing at this path.
rate_limited429Too many requests; scope says whether the store or this key is over, and Retry-After when to try again.
internal_error500Our fault. Quote the requestId.
shopify_error502Shopify refused or failed the change.
shopify_connection_lost503Shopify no longer accepts the app's access for this store; the merchant needs to open the app to reconnect it.
shopify_throttled503Shopify is throttling this store's requests. Retry after Retry-After.
shopify_unavailable503Shopify could not be reached.
unavailable503We could not check the key just now. Retry shortly.
shopify_timeout504Shopify took too long to answer.

Every other error code

CodeStatusMeaning
country_required400The address needs a country.
discount_code_required400No code was sent.
invalid_date400Not a valid date.
invalid_frequency400Not a frequency.
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
invalid_idempotency_key400Idempotency-Key is empty or longer than 255 characters.
invalid_json400The body is not valid JSON.
invalid_kind400Choose whether the item renews or is for the next order only.
invalid_pagination400limit is not 1 to 100, or cursor is not one this API returned.
invalid_price400A price is missing, negative or too large.
invalid_quantity400Quantity must be a whole number in the allowed range.
invalid_reason400reasonId or childId is not one of the store's cancellation reasons.
invalid_request400Something in the request is wrong; message says what and param names the field when there is one.
invalid_status400status is not a subscription status.
invalid_variant_id400Not a product variant id.
invalid_when400when must be immediate or endOfCycle.
line_id_required400The line to change is missing.
revision_id_required400This change is priced, so it needs the revisionId the price was given at.
app_plan_ended403The store's plan has ended. Reads work; changes other than cancel, pause, sync and previews are refused.
app_plan_locked403The store is over its plan's limit past the grace period. Reads work; changes other than cancel, pause, sync and previews are refused.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
customer_not_found404No customer with that id in this store.
discount_not_found404No such discount on this subscription.
line_not_found404No line with that id on this subscription.
subscription_not_found404No subscription with that id in this store.
cancellation_not_scheduled409The subscription is not set to end.
cancellation_scheduled409The subscription is already set to end.
charge_in_progress409An order for this subscription is being charged now. Retry in a minute.
charging_disabled409Charging is turned off, so nothing would be shipped.
conflict409The request conflicts with the state of the subscription; message says how.
delivery_option_unavailable409The delivery option chosen is no longer offered for that address. Preview again.
discount_already_applied409The code is already on this subscription.
discount_does_not_combine409The code does not combine with a discount already on the subscription.
discount_running409A cancellation discount is running; change the frequency once it ends.
frequency_not_offered409That frequency is not offered for everything on the subscription.
payment_recovering409A failed payment is being retried.
request_in_progress409A request with this Idempotency-Key is still running.
revision_conflict409The subscription has changed since revisionId. Read it, or preview again, and retry.
same_frequency409The subscription already has that frequency.
schedule_changed409The date of the order changed. Read the subscription and retry.
subscription_not_active409Only an active subscription can do this.
subscription_not_paused409The subscription is not paused.
body_too_large413The body is too large.
country_not_shipped422The store does not ship to that country.
date_in_past422The new date is not in the future. To charge now, use ship-now.
discount_code_not_found422No discount with that code, or it has been deleted.
discount_currency_mismatch422A fixed-amount code in another currency than the subscription's.
discount_expired422The code has expired.
discount_minimum_not_met422The subscription does not meet the code's minimum.
discount_no_eligible_lines422Nothing on the subscription is covered by the code.
discount_not_applicable422The code cannot be applied to this subscription.
discount_not_started422The code has not started yet.
discount_used_up422The code has reached its usage limit.
idempotency_key_reused422The same Idempotency-Key with a different request.
last_line422The subscription's last line cannot be removed; cancel instead.
no_billing_interval422The subscription has no billing interval to resume on.
no_delivery_rates422Shopify has no delivery rates for that address.
no_upcoming_order422The subscription has no upcoming order.
not_shipped422The subscription is picked up or delivered locally, so it has no shipping address to change.
payment_update_not_sendable422The email cannot be sent: no address, a suppressed address, or a payment method Shopify cannot send a link for.
prepaid_subscription422Not possible on a prepaid subscription.
product_unavailable422The product is deleted or not active.
same_variant422That variant is already on this line.
subscription_closed422The subscription is cancelled or expired.
subscription_paused422The subscription is paused; resume it first.
too_many_lines422The subscription has as many lines as it can hold.
unprocessable422The request is understood but cannot be carried out; message says why.
payment_update_recently_sent429An update email was sent moments ago. Try again in a few minutes.