Developers
Subscriptions
Read your subscriptions and make every change your staff can make in Vanix. Paths take a subscription's numeric id or its gid.
The subscription object
What every subscription endpoint answers with. In a list, a subscription has its first 50 items (linesTruncated says when there are more); reading one subscription always gives every item.
For what the next order will charge, read totals.total. Don't add up the lines yourself: prices, discounts, delivery and tax interact in ways only the total accounts for.
| Field | Type | Description |
|---|---|---|
id | string | |
gid | string | |
revisionId | string or null | Send it back on a priced change; see Concurrency. |
status | string | One of ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED. |
createdAt | date-time or null | |
updatedAt | date-time or null | |
customer | object or null | |
customer.id | string | |
customer.gid | string | |
customer.displayName | string or null | |
customer.firstName | string or null | |
customer.lastName | string or null | |
customer.email | string or null | |
nextBilling | object or null | When the next charge is made. Null while paused or ended. On a prepaid subscription the deliveries in between are not charges. |
nextBilling.date | date | In the store's time zone. |
nextBilling.at | date-time | |
prepaid | boolean | Billed less often than delivered. |
billingFrequency | object or null | |
billingFrequency.interval | string | One of DAY, WEEK, MONTH, YEAR. |
billingFrequency.intervalCount | integer | |
billingFrequency.minCycles | integer or null | |
billingFrequency.maxCycles | integer or null | |
billingFrequency.anchors | array of Anchor | |
deliveryFrequency | object or null | |
deliveryFrequency.interval | string | One of DAY, WEEK, MONTH, YEAR. |
deliveryFrequency.intervalCount | integer | |
deliveryFrequency.anchors | array of Anchor | |
lines | array of Line | |
linesCount | integer | |
linesTruncated | boolean | True in a list when there are more than 50 lines; the single read always has them all. |
delivery | object or null | |
delivery.method | string or null | One of SHIPPING, LOCAL_DELIVERY, PICKUP. |
delivery.option | object or null | |
delivery.option.code | string or null | |
delivery.option.title | string or null | |
delivery.option.description | string or null | |
delivery.price | Money or null | |
delivery.address | Address or null | |
delivery.phone | string or null | |
delivery.instructions | string or null | |
totals | object | Rely on total: what the next order charges. Do not add the parts up; where prices include tax it is already inside them. |
totals.lines | Money or null | |
totals.delivery | Money or null | |
totals.tax | Money or null | |
totals.total | Money or null | |
totals.estimated | boolean | Shopify has not yet projected the order with tax; total is lines plus delivery. |
discounts | array of Discount | |
paymentMethod | Payment method or null | |
payment | object | |
payment.lastStatus | string or null | SUCCEEDED, FAILED… |
payment.lastErrorType | string or null | PAYMENT_ERROR, INVENTORY_ERROR, CUSTOMER_ERROR or OTHER. |
payment.failing | boolean | |
payment.nextRetryAt | date-time or null | |
pendingCancellation | object or null | An end-of-cycle cancel not yet carried out. |
pendingCancellation.effectiveAt | date-time | |
pendingCancellation.scheduledBy | string or null | One of customer, merchant, api. |
pendingCancellation.reason | string or null | |
originOrder | object or null | |
originOrder.id | string | |
originOrder.gid | string | |
originOrder.name | string or null | |
originOrder.createdAt | date-time or null | |
note | string or null | |
customAttributes | array of object | |
customAttributes[].key | string | |
customAttributes[].value | string or null |
{
"id": "26893631718",
"gid": "gid://shopify/SubscriptionContract/26893631718",
"revisionId": "860896133350",
"status": "ACTIVE",
"createdAt": "2026-08-14T15:42:10Z",
"updatedAt": "2026-10-14T16:00:03Z",
"customer": {
"id": "7712345678901",
"gid": "gid://shopify/Customer/7712345678901",
"displayName": "Jane Doe",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@example.com"
},
"nextBilling": {
"date": "2026-11-14",
"at": "2026-11-14T16:00:00Z"
},
"prepaid": false,
"billingFrequency": {
"interval": "MONTH",
"intervalCount": 1,
"minCycles": null,
"maxCycles": null,
"anchors": []
},
"deliveryFrequency": {
"interval": "MONTH",
"intervalCount": 1,
"anchors": []
},
"lines": [
{
"id": "gid://shopify/SubscriptionLine/5b1e8a40-3c2d-4f7e-9a61-0d2c4b8e7f13",
"product": {
"id": "8123456789012",
"gid": "gid://shopify/Product/8123456789012",
"title": "House Blend Coffee"
},
"variant": {
"id": "44102341787878",
"gid": "gid://shopify/ProductVariant/44102341787878",
"title": "1 kg / Whole bean",
"sku": "HB-1KG-WB"
},
"quantity": 1,
"price": {
"amount": "21.60",
"currencyCode": "USD"
},
"basePrice": {
"amount": "24.00",
"currencyCode": "USD"
},
"total": {
"amount": "21.60",
"currencyCode": "USD"
},
"sellingPlan": {
"id": "691234567890",
"gid": "gid://shopify/SellingPlan/691234567890",
"name": "Delivered every month, 10% off"
},
"priceSchedule": [],
"oneTime": false,
"imageUrl": "https://cdn.shopify.com/s/files/1/0000/0001/products/house-blend.jpg"
}
],
"linesCount": 1,
"linesTruncated": false,
"delivery": {
"method": "SHIPPING",
"option": {
"code": "standard-shipping",
"title": "Standard",
"description": null
},
"price": {
"amount": "5.00",
"currencyCode": "USD"
},
"address": {
"firstName": "Jane",
"lastName": "Doe",
"company": null,
"address1": "12 Harbour Street",
"address2": null,
"city": "Portland",
"province": "Oregon",
"provinceCode": "OR",
"zip": "97201",
"country": "United States",
"countryCode": "US",
"phone": "+15035550123"
},
"phone": null,
"instructions": null
},
"totals": {
"lines": {
"amount": "21.60",
"currencyCode": "USD"
},
"delivery": {
"amount": "5.00",
"currencyCode": "USD"
},
"tax": {
"amount": "0.00",
"currencyCode": "USD"
},
"total": {
"amount": "26.60",
"currencyCode": "USD"
},
"estimated": false
},
"discounts": [],
"paymentMethod": {
"type": "CARD",
"brand": "Visa",
"lastDigits": "4242",
"expiryMonth": 8,
"expiryYear": 2028,
"expiresSoon": false,
"wallet": null,
"paypalEmail": null,
"inactive": false,
"revoked": false
},
"payment": {
"lastStatus": "SUCCEEDED",
"lastErrorType": null,
"failing": false,
"nextRetryAt": null
},
"pendingCancellation": null,
"originOrder": {
"id": "6012345678901",
"gid": "gid://shopify/Order/6012345678901",
"name": "#1001",
"createdAt": "2026-08-14T15:42:10Z"
},
"note": null,
"customAttributes": []
}Reading subscriptions
List subscriptions
GET /v1/subscriptions
Most recently changed first. Lines stop at 50 per subscription here (linesTruncated); read one subscription for them all.
| Parameter | In | Description |
|---|---|---|
status | query | One of ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED. |
customerId | query | One customer's subscriptions: a numeric id or gid. |
limit | query | Default 25. |
cursor | query | nextCursor from the previous page. |
Request
curl "https://api.vanixcommerce.com/v1/subscriptions?status=ACTIVE" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"data": [
{ "id": "26893631718", "gid": "gid://shopify/SubscriptionContract/26893631718", "status": "ACTIVE", … }
],
"nextCursor": null
}Errors (4)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
invalid_pagination | 400 | limit is not 1 to 100, or cursor is not one this API returned. |
invalid_status | 400 | status is not a subscription status. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
One subscription
GET /v1/subscriptions/{id}
Always every line, read from Shopify when there are more than 50.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Request
curl "https://api.vanixcommerce.com/v1/subscriptions/26893631718" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"subscription": { "id": "26893631718", "gid": "gid://shopify/SubscriptionContract/26893631718", … }
}Errors (3)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
Changing a subscription
Every change needs the subscriptions:write scope, and answers the subscription as it is afterwards, with these when the change has them:
| Field | Type | Description |
|---|---|---|
subscription | Subscription | |
notification | object | |
notification.sent | boolean | Whether the customer was emailed. False when not asked to, or when it could not be sent. |
warnings | array of Warning | |
charge | object | |
charge.state | string | One of SUCCEEDED, FAILED, ACTION_REQUIRED, PENDING, RETRYING, SKIPPED. |
Changes that are priced (a swap, an add, removing an item, the address and discount codes) have a preview to call first, and need the revisionId it answers. Cancelling needs a revisionId too, which you can take from the subscription. Previews and revisions
Pausing and cancelling
Pause
POST /v1/subscriptions/{id}/pause
Charges stop until it is resumed.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
notifyCustomer | boolean | Email the customer about the change. Default false. |
revisionId | string | Optional. Given, the change is refused with revision_conflict if the subscription has moved on. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/pause" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"notifyCustomer": true
}'Response
{
"subscription": { "id": "26893631718", "status": "PAUSED", "revisionId": "860896133351", … },
"notification": {
"sent": true
}
}Errors (13)
| Code | Status | Meaning |
|---|---|---|
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_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
cancellation_scheduled | 409 | The subscription is already set to end. |
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. |
subscription_not_active | 409 | Only an active subscription can do this. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Resume
POST /v1/subscriptions/{id}/resume
The next charge is one interval from now.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
notifyCustomer | boolean | Email the customer about the change. Default false. |
revisionId | string | Optional. Given, the change is refused with revision_conflict if the subscription has moved on. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/resume" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"notifyCustomer": true
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … },
"notification": {
"sent": true
}
}Errors (15)
| Code | Status | Meaning |
|---|---|---|
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_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
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. |
subscription_not_found | 404 | No subscription with that id in this store. |
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. |
subscription_not_paused | 409 | The subscription is not paused. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
no_billing_interval | 422 | The subscription has no billing interval to resume on. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Cancel
POST /v1/subscriptions/{id}/cancel
Now, or at the end of the paid cycle (pendingCancellation until then).
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
when Required | string | One of immediate, endOfCycle. |
revisionId Required | string | The revisionId the preview gave. Required: a price confirmed against one version must not be charged against another. |
reasonId | string | One of the store's cancellation reasons. |
childId | string | |
note | string | |
notifyCustomer | boolean | Email the customer about the change. Default false. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/cancel" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"when": "endOfCycle",
"revisionId": "860896133350",
"notifyCustomer": true
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … },
"notification": {
"sent": true
}
}Errors (18)
| Code | Status | Meaning |
|---|---|---|
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_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_when | 400 | when must be immediate or endOfCycle. |
revision_id_required | 400 | This change is priced, so it needs the revisionId the price was given at. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
cancellation_scheduled | 409 | The subscription is already set to end. |
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. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
no_delivery_rates | 422 | Shopify has no delivery rates for that address. |
no_upcoming_order | 422 | The subscription has no upcoming order. |
subscription_closed | 422 | The subscription is cancelled or expired. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Keep a subscription set to end
POST /v1/subscriptions/{id}/cancel/withdraw
Calls off a pending end-of-cycle cancel, whoever scheduled it.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
notifyCustomer | boolean | Email the customer about the change. Default false. |
revisionId | string | Optional. Given, the change is refused with revision_conflict if the subscription has moved on. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/cancel/withdraw" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"notifyCustomer": true
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … },
"notification": {
"sent": true
}
}Errors (14)
| Code | Status | Meaning |
|---|---|---|
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. |
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. |
subscription_not_found | 404 | No subscription with that id in this store. |
cancellation_not_scheduled | 409 | The subscription is not set to end. |
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. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
subscription_closed | 422 | The subscription is cancelled or expired. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
The next order
Move the next charge
POST /v1/subscriptions/{id}/reschedule
date is a day in the store's time zone, charged at the time of day the subscription bills at now; at is an exact moment. Not in the past: to charge now, use ship-now.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
date | date | |
at | date-time | |
revisionId | string | Optional. Given, the change is refused with revision_conflict if the subscription has moved on. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/reschedule" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"date": "2026-11-20"
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … }
}Errors (15)
| Code | Status | Meaning |
|---|---|---|
invalid_date | 400 | Not a valid date. |
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. |
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. |
subscription_not_found | 404 | No subscription with that id in this store. |
charge_in_progress | 409 | An order for this subscription is being charged now. Retry in a minute. |
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. |
body_too_large | 413 | The body is too large. |
date_in_past | 422 | The new date is not in the future. To charge now, use ship-now. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
subscription_closed | 422 | The subscription is cancelled or expired. |
Where skipping would move the next charge
GET /v1/subscriptions/{id}/skip
Writes nothing.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Request
curl "https://api.vanixcommerce.com/v1/subscriptions/26893631718/skip" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"preview": {
"allowed": true,
"reason": null,
"from": {
"date": "2026-11-14",
"at": "2026-11-14T16:00:00Z"
},
"to": {
"date": "2026-12-14",
"at": "2026-12-14T16:00:00Z"
}
},
"revisionId": "860896133350"
}Response fields
| Field | Type | Description |
|---|---|---|
preview | object | |
preview.allowed | boolean | |
preview.reason | string or null | The error code the skip would answer. |
preview.from | object or null | |
preview.from.date | date | |
preview.from.at | date-time | |
preview.to | object or null | |
preview.to.date | date | |
preview.to.at | date-time | |
revisionId | string | Send it with the write. |
Errors (3)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
Skip the next order
POST /v1/subscriptions/{id}/skip
The next charge moves one interval on. Refused while a payment is being retried (reschedule instead) and on prepaid subscriptions.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
from | date-time | The nextBilling.at being skipped. Given, the skip is refused with schedule_changed if the date has moved. |
revisionId | string | Optional. Given, the change is refused with revision_conflict if the subscription has moved on. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/skip" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "2026-11-14T16:00:00Z"
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … }
}Errors (20)
| Code | Status | Meaning |
|---|---|---|
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_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
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. |
subscription_not_found | 404 | No subscription with that id in this store. |
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. |
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. |
schedule_changed | 409 | The date of the order changed. Read the subscription and retry. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
no_upcoming_order | 422 | The subscription has no upcoming order. |
prepaid_subscription | 422 | Not possible on a prepaid subscription. |
subscription_closed | 422 | The subscription is cancelled or expired. |
subscription_paused | 422 | The subscription is paused; resume it first. |
Charge the next order now
POST /v1/subscriptions/{id}/ship-now
Charges now and moves the schedule on from today. Send an Idempotency-Key.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
revisionId | string | Optional. Given, the change is refused with revision_conflict if the subscription has moved on. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/ship-now" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Idempotency-Key: 8e0f6c1a-5b7d-4f0e-9a2c-3d1b2e4f5a6b"Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … },
"charge": {
"state": "SUCCEEDED"
}
}Errors (19)
| Code | Status | Meaning |
|---|---|---|
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_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
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. |
subscription_not_found | 404 | No subscription with that id in this store. |
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. |
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. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
no_delivery_rates | 422 | Shopify has no delivery rates for that address. |
subscription_closed | 422 | The subscription is cancelled or expired. |
subscription_paused | 422 | The subscription is paused; resume it first. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Items
Change quantities
POST /v1/subscriptions/{id}/quantities
Lines not listed are left alone.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
lines Required | array of object | |
lines[].id Required | string | A line id from the subscription. |
lines[].quantity Required | integer | |
revisionId | string | Optional. Given, the change is refused with revision_conflict if the subscription has moved on. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/quantities" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"lines": [
{
"id": "gid://shopify/SubscriptionLine/5b1e8a40-3c2d-4f7e-9a61-0d2c4b8e7f13",
"quantity": 2
}
]
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … }
}Errors (16)
| Code | Status | Meaning |
|---|---|---|
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_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
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. |
line_not_found | 404 | No line with that id on this subscription. |
subscription_not_found | 404 | No subscription with that id in this store. |
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. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
no_delivery_rates | 422 | Shopify has no delivery rates for that address. |
subscription_closed | 422 | The subscription is cancelled or expired. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Price a line replacement
POST /v1/subscriptions/{id}/swap/preview
Writes nothing.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
| Field | Type | Description |
|---|---|---|
lineId Required | string | A line id from the subscription. |
variantId Required | string | A product variant id or gid. |
price | string | A decimal amount in the subscription's currency, such as "12.50". Leave it out to take the price the store's rules give. |
quantity | integer | |
attachPlan | boolean | Put the new product on a selling plan at the subscription's frequency when it has one (the default). |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/swap/preview" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"lineId": "gid://shopify/SubscriptionLine/5b1e8a40-3c2d-4f7e-9a61-0d2c4b8e7f13",
"variantId": "44102341787879"
}'Response
{
"preview": {
"lineId": "gid://shopify/SubscriptionLine/5b1e8a40-3c2d-4f7e-9a61-0d2c4b8e7f13",
"from": {
"product": {
"id": "8123456789012",
"gid": "gid://shopify/Product/8123456789012",
"title": "House Blend Coffee"
},
"variant": {
"id": "44102341787878",
"gid": "gid://shopify/ProductVariant/44102341787878",
"title": "1 kg / Whole bean"
},
"price": {
"amount": "21.60",
"currencyCode": "USD"
},
"basePrice": {
"amount": "24.00",
"currencyCode": "USD"
},
"sellingPlan": {
"id": "691234567890",
"gid": "gid://shopify/SellingPlan/691234567890",
"name": "Delivered every month, 10% off"
}
},
"to": {
"product": {
"id": "8123456789013",
"gid": "gid://shopify/Product/8123456789013",
"title": "Decaf Blend"
},
"variant": {
"id": "44102341787879",
"gid": "gid://shopify/ProductVariant/44102341787879",
"title": "1 kg / Ground"
},
"price": {
"amount": "22.50",
"currencyCode": "USD"
},
"basePrice": {
"amount": "25.00",
"currencyCode": "USD"
},
"sellingPlan": {
"id": "691234567890",
"gid": "gid://shopify/SellingPlan/691234567890",
"name": "Delivered every month, 10% off"
}
},
"quantity": {
"from": 1,
"to": 1
},
"defaultPrice": {
"amount": "22.50",
"currencyCode": "USD"
},
"priceSetByMerchant": false,
"customerCanSwap": true,
"warnings": []
},
"revisionId": "860896133350"
}Response fields
| Field | Type | Description |
|---|---|---|
preview | object | |
preview.lineId | string | |
preview.from | object | |
preview.from.product | object or null | |
preview.from.product.id | string | |
preview.from.product.gid | string | |
preview.from.product.title | string or null | |
preview.from.variant | object or null | |
preview.from.variant.id | string | |
preview.from.variant.gid | string | |
preview.from.variant.title | string or null | |
preview.from.price | Money or null | |
preview.from.basePrice | Money or null | |
preview.from.sellingPlan | object or null | |
preview.from.sellingPlan.id | string | |
preview.from.sellingPlan.gid | string | |
preview.from.sellingPlan.name | string or null | |
preview.to | object | |
preview.to.product | object or null | |
preview.to.product.id | string | |
preview.to.product.gid | string | |
preview.to.product.title | string or null | |
preview.to.variant | object or null | |
preview.to.variant.id | string | |
preview.to.variant.gid | string | |
preview.to.variant.title | string or null | |
preview.to.price | Money or null | |
preview.to.basePrice | Money or null | |
preview.to.sellingPlan | object or null | |
preview.to.sellingPlan.id | string | |
preview.to.sellingPlan.gid | string | |
preview.to.sellingPlan.name | string or null | |
preview.quantity | object | |
preview.quantity.from | integer | |
preview.quantity.to | integer | |
preview.defaultPrice | Money or null | |
preview.priceSetByMerchant | boolean | |
preview.customerCanSwap | boolean | |
preview.warnings | array of Warning | |
revisionId | string | Send it with the write. |
Errors (13)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
invalid_json | 400 | The body is not valid JSON. |
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_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
invalid_variant_id | 400 | Not a product variant id. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
line_not_found | 404 | No line with that id on this subscription. |
subscription_not_found | 404 | No subscription with that id in this store. |
body_too_large | 413 | The body is too large. |
product_unavailable | 422 | The product is deleted or not active. |
same_variant | 422 | That variant is already on this line. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Replace a line
POST /v1/subscriptions/{id}/swap
With the revisionId from the preview.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
lineId Required | string | A line id from the subscription. |
variantId Required | string | A product variant id or gid. |
price | string | A decimal amount in the subscription's currency, such as "12.50". Leave it out to take the price the store's rules give. |
quantity | integer | |
attachPlan | boolean | Put the new product on a selling plan at the subscription's frequency when it has one (the default). |
revisionId Required | string | The revisionId the preview gave. Required: a price confirmed against one version must not be charged against another. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/swap" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"lineId": "gid://shopify/SubscriptionLine/5b1e8a40-3c2d-4f7e-9a61-0d2c4b8e7f13",
"variantId": "44102341787879",
"revisionId": "860896133350"
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … },
"warnings": [
{
"code": "past_cutoff",
"message": "The next order may already be being prepared.",
"closesAt": "2026-11-09T16:00:00Z",
"deliveries": null
}
]
}Errors (24)
| Code | Status | Meaning |
|---|---|---|
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_price | 400 | A price is missing, negative or too large. |
invalid_quantity | 400 | Quantity must be a whole number in the allowed range. |
invalid_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
invalid_variant_id | 400 | Not a product variant id. |
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. |
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_scheduled | 409 | The subscription is already set to end. |
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. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
no_delivery_rates | 422 | Shopify has no delivery rates for that address. |
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. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Price an added line
POST /v1/subscriptions/{id}/add/preview
Writes nothing.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
| Field | Type | Description |
|---|---|---|
variantId Required | string | A product variant id or gid. |
kind | string | oneTime ships with the next order only and comes off after it is charged. One of recurring, oneTime. Default "recurring". |
quantity | integer | |
price | string | A decimal amount in the subscription's currency, such as "12.50". Leave it out to take the price the store's rules give. |
attachPlan | boolean | Put the new product on a selling plan at the subscription's frequency when it has one (the default). |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/add/preview" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"variantId": "44102341787878",
"kind": "oneTime",
"quantity": 1
}'Response
{
"preview": {
"kind": "oneTime",
"product": {
"id": "8123456789012",
"gid": "gid://shopify/Product/8123456789012",
"title": "House Blend Coffee"
},
"variant": {
"id": "44102341787878",
"gid": "gid://shopify/ProductVariant/44102341787878",
"title": "1 kg / Whole bean"
},
"quantity": 1,
"price": {
"amount": "24.00",
"currencyCode": "USD"
},
"basePrice": {
"amount": "24.00",
"currencyCode": "USD"
},
"defaultPrice": {
"amount": "24.00",
"currencyCode": "USD"
},
"priceSetByMerchant": false,
"sellingPlanName": null,
"customerCanSwap": false,
"discounts": [],
"warnings": []
},
"revisionId": "860896133350"
}Response fields
| Field | Type | Description |
|---|---|---|
preview | object | |
preview.kind | string | One of recurring, oneTime. |
preview.product | object or null | |
preview.product.id | string | |
preview.product.gid | string | |
preview.product.title | string or null | |
preview.variant | object or null | |
preview.variant.id | string | |
preview.variant.gid | string | |
preview.variant.title | string or null | |
preview.quantity | integer | |
preview.price | Money or null | |
preview.basePrice | Money or null | |
preview.defaultPrice | Money or null | |
preview.priceSetByMerchant | boolean | |
preview.sellingPlanName | string or null | |
preview.customerCanSwap | boolean | |
preview.discounts | array of object | |
preview.discounts[].code | string | |
preview.discounts[].applies | boolean | |
preview.warnings | array of Warning | |
revisionId | string | Send it with the write. |
Errors (13)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
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_price | 400 | A price is missing, negative or too large. |
invalid_quantity | 400 | Quantity must be a whole number in the allowed range. |
invalid_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
invalid_variant_id | 400 | Not a product variant id. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
body_too_large | 413 | The body is too large. |
product_unavailable | 422 | The product is deleted or not active. |
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. |
Add a line
POST /v1/subscriptions/{id}/add
With the revisionId from the preview. Send an Idempotency-Key: nothing else stops a retried add adding twice.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
variantId Required | string | A product variant id or gid. |
kind | string | oneTime ships with the next order only and comes off after it is charged. One of recurring, oneTime. Default "recurring". |
quantity | integer | |
price | string | A decimal amount in the subscription's currency, such as "12.50". Leave it out to take the price the store's rules give. |
attachPlan | boolean | Put the new product on a selling plan at the subscription's frequency when it has one (the default). |
revisionId Required | string | The revisionId the preview gave. Required: a price confirmed against one version must not be charged against another. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/add" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Idempotency-Key: 8e0f6c1a-5b7d-4f0e-9a2c-3d1b2e4f5a6b" \
-H "Content-Type: application/json" \
-d '{
"variantId": "44102341787878",
"kind": "oneTime",
"quantity": 1,
"revisionId": "860896133350"
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … },
"warnings": [
{
"code": "past_cutoff",
"message": "The next order may already be being prepared.",
"closesAt": "2026-11-09T16:00:00Z",
"deliveries": null
}
]
}Errors (24)
| Code | Status | Meaning |
|---|---|---|
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_price | 400 | A price is missing, negative or too large. |
invalid_quantity | 400 | Quantity must be a whole number in the allowed range. |
invalid_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
invalid_variant_id | 400 | Not a product variant id. |
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. |
subscription_not_found | 404 | No subscription with that id in this store. |
cancellation_scheduled | 409 | The subscription is already set to end. |
conflict | 409 | The request conflicts with the state of the subscription; message says how. |
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. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
no_delivery_rates | 422 | Shopify has no delivery rates for that address. |
product_unavailable | 422 | The product is deleted or not active. |
subscription_closed | 422 | The subscription is cancelled or expired. |
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. |
Check a line removal
POST /v1/subscriptions/{id}/remove-line/preview
Writes nothing.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
| Field | Type | Description |
|---|---|---|
lineId Required | string | A line id from the subscription. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/remove-line/preview" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"lineId": "gid://shopify/SubscriptionLine/5b1e8a40-3c2d-4f7e-9a61-0d2c4b8e7f13"
}'Response
{
"preview": {
"kind": "recurring",
"lastLine": false,
"warnings": []
},
"revisionId": "860896133350"
}Response fields
| Field | Type | Description |
|---|---|---|
preview | object | |
preview.kind | string | One of recurring, oneTime. |
preview.lastLine | boolean | The last renewing line cannot be removed; cancel instead. |
preview.warnings | array of Warning | |
revisionId | string | Send it with the write. |
Errors (6)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
invalid_json | 400 | The body is not valid JSON. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
line_not_found | 404 | No line with that id on this subscription. |
subscription_not_found | 404 | No subscription with that id in this store. |
body_too_large | 413 | The body is too large. |
Remove a line
POST /v1/subscriptions/{id}/remove-line
The last renewing line is refused with last_line; cancel instead.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
lineId Required | string | A line id from the subscription. |
revisionId Required | string | The revisionId the preview gave. Required: a price confirmed against one version must not be charged against another. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/remove-line" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"lineId": "gid://shopify/SubscriptionLine/5b1e8a40-3c2d-4f7e-9a61-0d2c4b8e7f13",
"revisionId": "860896133350"
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … },
"warnings": [
{
"code": "past_cutoff",
"message": "The next order may already be being prepared.",
"closesAt": "2026-11-09T16:00:00Z",
"deliveries": null
}
]
}Errors (19)
| Code | Status | Meaning |
|---|---|---|
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. |
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. |
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_scheduled | 409 | The subscription is already set to end. |
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. |
body_too_large | 413 | The body is too large. |
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_delivery_rates | 422 | Shopify has no delivery rates for that address. |
subscription_closed | 422 | The subscription is cancelled or expired. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Frequency
Frequencies it can move to
GET /v1/subscriptions/{id}/frequency-options
Each priced, line by line.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Request
curl "https://api.vanixcommerce.com/v1/subscriptions/26893631718/frequency-options" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"allowed": true,
"reason": null,
"current": {
"interval": "MONTH",
"intervalCount": 1
},
"options": [
{
"interval": "WEEK",
"intervalCount": 6,
"lines": [
{
"lineId": "gid://shopify/SubscriptionLine/5b1e8a40-3c2d-4f7e-9a61-0d2c4b8e7f13",
"from": {
"sellingPlanName": "Delivered every month, 10% off",
"price": {
"amount": "21.60",
"currencyCode": "USD"
}
},
"to": {
"sellingPlanName": "Delivered every 6 weeks, 10% off",
"price": {
"amount": "21.60",
"currencyCode": "USD"
}
}
}
],
"subtotal": {
"from": {
"amount": "21.60",
"currencyCode": "USD"
},
"to": {
"amount": "21.60",
"currencyCode": "USD"
}
},
"priceChanged": false
}
],
"revisionId": "860896133350"
}Response fields
| Field | Type | Description |
|---|---|---|
allowed | boolean | |
reason | string or null | |
current | object or null | |
current.interval | string | |
current.intervalCount | integer | |
options | array of object | |
options[].interval | string | |
options[].intervalCount | integer | |
options[].lines | array of object | |
options[].lines[].lineId | string | |
options[].lines[].from | object | |
options[].lines[].from.sellingPlanName | string or null | |
options[].lines[].from.price | Money or null | |
options[].lines[].to | object | |
options[].lines[].to.sellingPlanName | string or null | |
options[].lines[].to.price | Money or null | |
options[].subtotal | object | |
options[].subtotal.from | Money or null | |
options[].subtotal.to | Money or null | |
options[].priceChanged | boolean | |
revisionId | string or null |
Errors (3)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
Change the frequency
POST /v1/subscriptions/{id}/frequency
To one of frequency-options. The next charge date does not move; the new interval runs from it.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
interval Required | string | One of DAY, WEEK, MONTH, YEAR. |
intervalCount Required | integer | |
revisionId | string | Optional. Given, the change is refused with revision_conflict if the subscription has moved on. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/frequency" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"interval": "WEEK",
"intervalCount": 6
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … }
}Errors (21)
| Code | Status | Meaning |
|---|---|---|
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. |
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. |
subscription_not_found | 404 | No subscription with that id in this store. |
cancellation_scheduled | 409 | The subscription is already set to end. |
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. |
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. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
no_delivery_rates | 422 | Shopify has no delivery rates for that address. |
prepaid_subscription | 422 | Not possible on a prepaid subscription. |
subscription_closed | 422 | The subscription is cancelled or expired. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Delivery address
Delivery options for an address
POST /v1/subscriptions/{id}/address/preview
The rates Shopify offers for the address. Writes nothing.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
| Field | Type | Description |
|---|---|---|
address Required | object | firstName, lastName, company, address1, address2, city, province or provinceCode, zip, countryCode, phone. |
address.firstName | string | |
address.lastName | string | |
address.company | string | |
address.address1 | string | |
address.address2 | string | |
address.city | string | |
address.province | string | |
address.provinceCode | string | |
address.zip | string | |
address.countryCode Required | string | |
address.phone | string |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/address/preview" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": {
"firstName": "Jane",
"lastName": "Doe",
"address1": "12 Harbour Street",
"city": "Portland",
"provinceCode": "OR",
"zip": "97201",
"countryCode": "US",
"phone": "+15035550123"
}
}'Response
{
"preview": {
"address": {
"firstName": "Jane",
"lastName": "Doe",
"company": null,
"address1": "12 Harbour Street",
"address2": null,
"city": "Portland",
"province": "Oregon",
"provinceCode": "OR",
"zip": "97201",
"country": "United States",
"countryCode": "US",
"phone": "+15035550123"
},
"deliveryOptions": [
{
"code": "standard-shipping",
"title": "Standard",
"description": null,
"price": {
"amount": "5.00",
"currencyCode": "USD"
},
"phoneRequired": false
}
],
"currentOptionCode": "standard-shipping",
"unchanged": false
},
"revisionId": "860896133350"
}Response fields
| Field | Type | Description |
|---|---|---|
preview | object | |
preview.address | Address | |
preview.deliveryOptions | array of object | |
preview.deliveryOptions[].code | string | |
preview.deliveryOptions[].title | string or null | |
preview.deliveryOptions[].description | string or null | |
preview.deliveryOptions[].price | Money or null | |
preview.deliveryOptions[].phoneRequired | boolean | |
preview.currentOptionCode | string or null | |
preview.unchanged | boolean | |
revisionId | string | Send it with the write. |
Errors (11)
| Code | Status | Meaning |
|---|---|---|
country_required | 400 | The address needs a country. |
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
invalid_json | 400 | The body is not valid JSON. |
invalid_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
body_too_large | 413 | The body is too large. |
country_not_shipped | 422 | The store does not ship to that country. |
no_delivery_rates | 422 | Shopify has no delivery rates for that address. |
not_shipped | 422 | The subscription is picked up or delivered locally, so it has no shipping address to change. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Change the delivery address
POST /v1/subscriptions/{id}/address
optionCode is one of the preview's deliveryOptions.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
address Required | object | firstName, lastName, company, address1, address2, city, province or provinceCode, zip, countryCode, phone. |
address.firstName | string | |
address.lastName | string | |
address.company | string | |
address.address1 | string | |
address.address2 | string | |
address.city | string | |
address.province | string | |
address.provinceCode | string | |
address.zip | string | |
address.countryCode Required | string | |
address.phone | string | |
optionCode Required | string | |
revisionId Required | string | The revisionId the preview gave. Required: a price confirmed against one version must not be charged against another. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/address" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": {
"firstName": "Jane",
"lastName": "Doe",
"address1": "12 Harbour Street",
"city": "Portland",
"provinceCode": "OR",
"zip": "97201",
"countryCode": "US",
"phone": "+15035550123"
},
"optionCode": "standard-shipping",
"revisionId": "860896133350"
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … }
}Errors (20)
| Code | Status | Meaning |
|---|---|---|
country_required | 400 | The address needs a country. |
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_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
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. |
subscription_not_found | 404 | No subscription with that id in this store. |
delivery_option_unavailable | 409 | The delivery option chosen is no longer offered for that address. Preview again. |
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. |
body_too_large | 413 | The body is too large. |
country_not_shipped | 422 | The store does not ship to that country. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
no_delivery_rates | 422 | Shopify has no delivery rates for that address. |
not_shipped | 422 | The subscription is picked up or delivered locally, so it has no shipping address to change. |
subscription_closed | 422 | The subscription is cancelled or expired. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Discount codes
Check a discount code
POST /v1/subscriptions/{id}/discounts/preview
Writes nothing.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
| Field | Type | Description |
|---|---|---|
code Required | string |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/discounts/preview" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "WELCOME10"
}'Response
{
"preview": {
"code": "WELCOME10",
"title": "WELCOME10",
"value": {
"type": "PERCENTAGE",
"percentage": 10,
"amount": null,
"appliesOnEachItem": null
},
"cycleLimit": 3,
"lineIds": ["gid://shopify/SubscriptionLine/5b1e8a40-3c2d-4f7e-9a61-0d2c4b8e7f13"],
"warnings": []
},
"revisionId": "860896133350"
}Response fields
| Field | Type | Description |
|---|---|---|
preview | object | |
preview.code | string | |
preview.title | string or null | |
preview.value | object | |
preview.value.type | string | One of PERCENTAGE, FIXED_AMOUNT. |
preview.value.percentage | number | |
preview.value.amount | Money or null | |
preview.value.appliesOnEachItem | boolean or null | |
preview.cycleLimit | integer or null | |
preview.lineIds | array of string | |
preview.warnings | array of Warning | |
revisionId | string | Send it with the write. |
Errors (16)
| Code | Status | Meaning |
|---|---|---|
discount_code_required | 400 | No code was sent. |
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
invalid_json | 400 | The body is not valid JSON. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
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. |
body_too_large | 413 | The body is too large. |
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. |
Add a discount code
POST /v1/subscriptions/{id}/discounts
A Shopify discount code, applied as it would be at checkout.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
code Required | string | |
revisionId Required | string | The revisionId the preview gave. Required: a price confirmed against one version must not be charged against another. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/discounts" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "WELCOME10",
"revisionId": "860896133350"
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … },
"warnings": [
{
"code": "past_cutoff",
"message": "The next order may already be being prepared.",
"closesAt": "2026-11-09T16:00:00Z",
"deliveries": null
}
]
}Errors (25)
| Code | Status | Meaning |
|---|---|---|
discount_code_required | 400 | No code was sent. |
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. |
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. |
subscription_not_found | 404 | No subscription with that id in this store. |
cancellation_scheduled | 409 | The subscription is already set to end. |
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. |
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. |
body_too_large | 413 | The body is too large. |
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. |
subscription_closed | 422 | The subscription is cancelled or expired. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Take a discount code off
POST /v1/subscriptions/{id}/discounts/remove
discountId is an id from the subscription's discounts. Only codes added through Vanix can be taken off here.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
| Field | Type | Description |
|---|---|---|
discountId Required | string | |
revisionId Required | string | The revisionId the preview gave. Required: a price confirmed against one version must not be charged against another. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/discounts/remove" \
-H "Authorization: Bearer $VANIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"discountId": "gid://shopify/SubscriptionManualDiscount/0d1b6a3e-7c2f-4e5a-9b8d-1f2e3c4d5a6b",
"revisionId": "860896133350"
}'Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … }
}Errors (17)
| Code | Status | Meaning |
|---|---|---|
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_request | 400 | Something in the request is wrong; message says what and param names the field when there is one. |
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. |
discount_not_found | 404 | No such discount on this subscription. |
subscription_not_found | 404 | No subscription with that id in this store. |
cancellation_scheduled | 409 | The subscription is already set to end. |
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. |
body_too_large | 413 | The body is too large. |
discount_code_not_found | 422 | No discount with that code, or it has been deleted. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
subscription_closed | 422 | The subscription is cancelled or expired. |
unprocessable | 422 | The request is understood but cannot be carried out; message says why. |
Payment method
Email the customer a payment update link
POST /v1/subscriptions/{id}/payment-update-email
Shopify's link to update the payment method. At most once every few minutes.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/payment-update-email" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … },
"notification": {
"sent": true
}
}Errors (13)
| Code | Status | Meaning |
|---|---|---|
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. |
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. |
subscription_not_found | 404 | No subscription with that id in this store. |
request_in_progress | 409 | A request with this Idempotency-Key is still running. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
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. |
subscription_closed | 422 | The subscription is cancelled or expired. |
payment_update_recently_sent | 429 | An update email was sent moments ago. Try again in a few minutes. |
Reading it again from Shopify
Read it again from Shopify
POST /v1/subscriptions/{id}/sync
For when a change made in Shopify admin has not reached us yet.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Idempotency-Key | header | Any string up to 255 characters. A repeat within 24 hours gets the first answer back, with Idempotent-Replayed: true. Use one on ship-now and add above all. |
Request
curl -X POST "https://api.vanixcommerce.com/v1/subscriptions/26893631718/sync" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"subscription": { "id": "26893631718", "status": "ACTIVE", "revisionId": "860896133351", … }
}Errors (8)
| Code | Status | Meaning |
|---|---|---|
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. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
request_in_progress | 409 | A request with this Idempotency-Key is still running. |
body_too_large | 413 | The body is too large. |
idempotency_key_reused | 422 | The same Idempotency-Key with a different request. |
History
What has happened to a subscription. These need subscriptions:read.
A subscription's orders
GET /v1/subscriptions/{id}/orders
Newest first, read live from Shopify. At most 50 a page.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
limit | query | Default 25. |
cursor | query | nextCursor from the previous page. |
Request
curl "https://api.vanixcommerce.com/v1/subscriptions/26893631718/orders" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"data": [
{
"id": "6012345678901",
"gid": "gid://shopify/Order/6012345678901",
"name": "#1042",
"kind": "renewal",
"createdAt": "2026-10-14T16:00:04Z",
"cancelledAt": null,
"financialStatus": "PAID",
"fulfillmentStatus": "FULFILLED",
"total": {
"amount": "26.60",
"currencyCode": "USD"
}
}
],
"nextCursor": null
}Errors (4)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
invalid_pagination | 400 | limit is not 1 to 100, or cursor is not one this API returned. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
A subscription's cancellation attempts
GET /v1/subscriptions/{id}/cancellation-attempts
Each time the customer opened the cancel flow, or staff or a key cancelled. Newest first, the last 20.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Request
curl "https://api.vanixcommerce.com/v1/subscriptions/26893631718/cancellation-attempts" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"data": [
{
"id": "6713f0c2a4b5d6e7f8091a2c",
"actor": {
"kind": "customer",
"name": null
},
"startedAt": "2026-10-02T08:11:40Z",
"completedAt": "2026-10-02T08:12:31Z",
"outcome": "saved",
"when": null,
"effectiveAt": null,
"reason": "I have too much coffee",
"followUp": null,
"note": null,
"offer": {
"kind": "delay",
"outcome": "accepted",
"discountPercent": null,
"orders": null,
"delayDays": 30
}
}
]
}Errors (3)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
A subscription's activity
GET /v1/subscriptions/{id}/activity
Newest first. A page can hold fewer than limit and still have more: follow nextCursor until it is null.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
limit | query | Default 25. |
cursor | query | nextCursor from the previous page. |
Request
curl "https://api.vanixcommerce.com/v1/subscriptions/26893631718/activity" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"data": [
{
"id": "evt_9b2f6a41c3d8e7f0",
"topic": "subscription.paused",
"occurredAt": "2026-10-20T14:03:12Z",
"subscription": {
"id": "26893631718",
"gid": "gid://shopify/SubscriptionContract/26893631718"
},
"customer": {
"id": "7712345678901",
"gid": "gid://shopify/Customer/7712345678901"
},
"actor": {
"kind": "api",
"name": "Warehouse sync"
},
"details": {
"from": "ACTIVE",
"to": "PAUSED"
}
}
],
"nextCursor": null
}Errors (4)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
invalid_pagination | 400 | limit is not 1 to 100, or cursor is not one this API returned. |
insufficient_scope | 403 | The key lacks the scope this needs; requiredScope names it. |
subscription_not_found | 404 | No subscription with that id in this store. |
Warnings
Previews, and some changes, answer warnings: things worth knowing before you go ahead, which never stop the change. Each has a code and a message in English. More codes may be added, so treat one you don't know as other and show its message.
| Field | Type | Description |
|---|---|---|
code | string | See x-warning-codes. |
message | string | |
closesAt | date-time | |
deliveries | integer |
| Code | Meaning |
|---|---|
out_of_stock | The variant is out of stock. |
no_selling_plan | The product has no selling plan at this frequency, so the line goes on without one. |
past_cutoff | The next order may already be being prepared (closesAt says when the cut-off was). |
payment_recovering | A failed payment is being retried; the change alters the amount retried. |
currency_mismatch | The subscription is billed in another currency than the store's. |
customer_cannot_swap | The customer will not be able to swap this line themselves. |
prepaid | A prepaid line's price is the whole cycle's (deliveries says how many). |
customer_already_used | The customer has used this code before. |
for_other_customers | The code is set for other customers. |
for_customer_segments | The code is set for customer segments. |
single_use_used | The code is single-use and has been used. |
other_discounts | The subscription has other discounts. |
not_all_lines | The code covers only some of the lines. |
other | Something new; read message. |
Other objects
The line object
An item on the subscription. price is what each unit costs now; basePrice is the product's own price before the plan's discount.
| Field | Type | Description |
|---|---|---|
id | string | A gid. Lines have no numeric id in Shopify. |
product | object or null | Null once the product is deleted. |
product.id | string | |
product.gid | string | |
product.title | string or null | |
variant | object or null | |
variant.id | string | |
variant.gid | string | |
variant.title | string or null | |
variant.sku | string or null | |
quantity | integer | |
price | Money or null | |
basePrice | Money or null | |
total | Money or null | |
sellingPlan | object or null | Null for a line added without a plan. |
sellingPlan.id | string | |
sellingPlan.gid | string | |
sellingPlan.name | string or null | |
priceSchedule | array of object | Price changes after a number of cycles, such as a first-order discount. |
priceSchedule[].afterCycle | integer | |
priceSchedule[].price | Money or null | |
oneTime | boolean | An item for the next order only; it comes off after the next successful charge. |
imageUrl | string or null |
{
"id": "gid://shopify/SubscriptionLine/5b1e8a40-3c2d-4f7e-9a61-0d2c4b8e7f13",
"product": {
"id": "8123456789012",
"gid": "gid://shopify/Product/8123456789012",
"title": "House Blend Coffee"
},
"variant": {
"id": "44102341787878",
"gid": "gid://shopify/ProductVariant/44102341787878",
"title": "1 kg / Whole bean",
"sku": "HB-1KG-WB"
},
"quantity": 1,
"price": {
"amount": "21.60",
"currencyCode": "USD"
},
"basePrice": {
"amount": "24.00",
"currencyCode": "USD"
},
"total": {
"amount": "21.60",
"currencyCode": "USD"
},
"sellingPlan": {
"id": "691234567890",
"gid": "gid://shopify/SellingPlan/691234567890",
"name": "Delivered every month, 10% off"
},
"priceSchedule": [],
"oneTime": false,
"imageUrl": "https://cdn.shopify.com/s/files/1/0000/0001/products/house-blend.jpg"
}The address object
| Field | Type | Description |
|---|---|---|
firstName | string or null | |
lastName | string or null | |
company | string or null | |
address1 | string or null | |
address2 | string or null | |
city | string or null | |
province | string or null | |
provinceCode | string or null | |
zip | string or null | |
country | string or null | |
countryCode | string or null | |
phone | string or null |
{
"firstName": "Jane",
"lastName": "Doe",
"company": null,
"address1": "12 Harbour Street",
"address2": null,
"city": "Portland",
"province": "Oregon",
"provinceCode": "OR",
"zip": "97201",
"country": "United States",
"countryCode": "US",
"phone": "+15035550123"
}The anchor object
A fixed day the subscription bills or delivers on, such as the 1st of each month.
| Field | Type | Description |
|---|---|---|
type | string or null | WEEKDAY, MONTHDAY or YEARDAY. |
day | integer or null | |
month | integer or null | |
cutoffDay | integer or null |
{
"type": "MONTHDAY",
"day": 1,
"month": null,
"cutoffDay": 5
}The discount object
| Field | Type | Description |
|---|---|---|
id | string | |
type | string or null | CODE_DISCOUNT, MANUAL or AUTOMATIC_DISCOUNT. |
title | string or null | |
code | string or null | The code, on a CODE_DISCOUNT. |
target | string or null | LINE_ITEM or SHIPPING_LINE. |
value | object | |
value.type | string | One of PERCENTAGE, FIXED_AMOUNT. |
value.percentage | number | |
value.amount | Money or null | |
value.appliesOnEachItem | boolean or null | |
cyclesUsed | integer or null | |
cycleLimit | integer or null | |
rejected | boolean | Shopify has stopped applying it. |
{
"id": "gid://shopify/SubscriptionManualDiscount/0d1b6a3e-7c2f-4e5a-9b8d-1f2e3c4d5a6b",
"type": "CODE_DISCOUNT",
"title": "WELCOME10",
"code": "WELCOME10",
"target": "LINE_ITEM",
"value": {
"type": "PERCENTAGE",
"percentage": 10,
"amount": null,
"appliesOnEachItem": null
},
"cyclesUsed": 2,
"cycleLimit": 3,
"rejected": false
}The payment method object
The method renewals are charged to. Card numbers are never shown, only the brand and last digits.
| Field | Type | Description |
|---|---|---|
type | string | OTHER is a method Shopify added after this was written. One of CARD, SHOP_PAY, PAYPAL, BANK_ACCOUNT, OTHER. |
brand | string or null | |
lastDigits | string or null | |
expiryMonth | integer or null | |
expiryYear | integer or null | |
expiresSoon | boolean | |
wallet | string or null | apple_pay, google_pay… when the card came from one. |
paypalEmail | string or null | |
inactive | boolean | |
revoked | boolean |
{
"type": "CARD",
"brand": "Visa",
"lastDigits": "4242",
"expiryMonth": 8,
"expiryYear": 2028,
"expiresSoon": false,
"wallet": null,
"paypalEmail": null,
"inactive": false,
"revoked": false
}The order object
An order the subscription made: the first order at checkout, or a renewal.
| Field | Type | Description |
|---|---|---|
id | string | |
gid | string | |
name | string or null | |
kind | string | One of firstOrder, renewal. |
createdAt | date-time or null | |
cancelledAt | date-time or null | |
financialStatus | string or null | |
fulfillmentStatus | string or null | |
total | Money or null |
{
"id": "6012345678901",
"gid": "gid://shopify/Order/6012345678901",
"name": "#1042",
"kind": "renewal",
"createdAt": "2026-10-14T16:00:04Z",
"cancelledAt": null,
"financialStatus": "PAID",
"fulfillmentStatus": "FULFILLED",
"total": {
"amount": "26.60",
"currencyCode": "USD"
}
}The cancellation attempt object
Each time the customer opened the cancel flow, or your staff or a key cancelled. reason and followUp are the reasons' labels as the customer saw them.
| Field | Type | Description |
|---|---|---|
id | string | |
actor | object | |
actor.kind | string | One of customer, merchant, api. |
actor.name | string or null | |
startedAt | date-time or null | |
completedAt | date-time or null | |
outcome | string or null | Null while in the flow, or when the customer left it. One of cancelled, scheduled, saved, withdrawn. |
when | string or null | One of immediate, endOfCycle, split. |
effectiveAt | date-time or null | |
reason | string or null | |
followUp | string or null | |
note | string or null | |
offer | object or null | |
offer.kind | string or null | |
offer.outcome | string or null | One of accepted, declined. |
offer.discountPercent | number or null | |
offer.orders | integer or null | |
offer.delayDays | integer or null |
{
"id": "6713f0c2a4b5d6e7f8091a2c",
"actor": {
"kind": "customer",
"name": null
},
"startedAt": "2026-10-02T08:11:40Z",
"completedAt": "2026-10-02T08:12:31Z",
"outcome": "saved",
"when": null,
"effectiveAt": null,
"reason": "I have too much coffee",
"followUp": null,
"note": null,
"offer": {
"kind": "delay",
"outcome": "accepted",
"discountPercent": null,
"orders": null,
"delayDays": 30
}
}