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.

EndpointWhat it does
GET /v1/subscriptionsList subscriptions
GET /v1/subscriptions/{id}One subscription
POST /v1/subscriptions/{id}/pausePause
POST /v1/subscriptions/{id}/resumeResume
POST /v1/subscriptions/{id}/cancelCancel
POST /v1/subscriptions/{id}/cancel/withdrawKeep a subscription set to end
POST /v1/subscriptions/{id}/rescheduleMove the next charge
GET /v1/subscriptions/{id}/skipWhere skipping would move the next charge
POST /v1/subscriptions/{id}/skipSkip the next order
POST /v1/subscriptions/{id}/ship-nowCharge the next order now
POST /v1/subscriptions/{id}/quantitiesChange quantities
POST /v1/subscriptions/{id}/swap/previewPrice a line replacement
POST /v1/subscriptions/{id}/swapReplace a line
POST /v1/subscriptions/{id}/add/previewPrice an added line
POST /v1/subscriptions/{id}/addAdd a line
POST /v1/subscriptions/{id}/remove-line/previewCheck a line removal
POST /v1/subscriptions/{id}/remove-lineRemove a line
GET /v1/subscriptions/{id}/frequency-optionsFrequencies it can move to
POST /v1/subscriptions/{id}/frequencyChange the frequency
POST /v1/subscriptions/{id}/address/previewDelivery options for an address
POST /v1/subscriptions/{id}/addressChange the delivery address
POST /v1/subscriptions/{id}/discounts/previewCheck a discount code
POST /v1/subscriptions/{id}/discountsAdd a discount code
POST /v1/subscriptions/{id}/discounts/removeTake a discount code off
POST /v1/subscriptions/{id}/payment-update-emailEmail the customer a payment update link
POST /v1/subscriptions/{id}/syncRead it again from Shopify
GET /v1/subscriptions/{id}/ordersA subscription's orders
GET /v1/subscriptions/{id}/cancellation-attemptsA subscription's cancellation attempts
GET /v1/subscriptions/{id}/activityA subscription's activity

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.

FieldTypeDescription
idstring
gidstring
revisionIdstring or nullSend it back on a priced change; see Concurrency.
statusstringOne of ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED.
createdAtdate-time or null
updatedAtdate-time or null
customerobject or null
customer.idstring
customer.gidstring
customer.displayNamestring or null
customer.firstNamestring or null
customer.lastNamestring or null
customer.emailstring or null
nextBillingobject or nullWhen the next charge is made. Null while paused or ended. On a prepaid subscription the deliveries in between are not charges.
nextBilling.datedateIn the store's time zone.
nextBilling.atdate-time
prepaidbooleanBilled less often than delivered.
billingFrequencyobject or null
billingFrequency.intervalstringOne of DAY, WEEK, MONTH, YEAR.
billingFrequency.intervalCountinteger
billingFrequency.minCyclesinteger or null
billingFrequency.maxCyclesinteger or null
billingFrequency.anchorsarray of Anchor
deliveryFrequencyobject or null
deliveryFrequency.intervalstringOne of DAY, WEEK, MONTH, YEAR.
deliveryFrequency.intervalCountinteger
deliveryFrequency.anchorsarray of Anchor
linesarray of Line
linesCountinteger
linesTruncatedbooleanTrue in a list when there are more than 50 lines; the single read always has them all.
deliveryobject or null
delivery.methodstring or nullOne of SHIPPING, LOCAL_DELIVERY, PICKUP.
delivery.optionobject or null
delivery.option.codestring or null
delivery.option.titlestring or null
delivery.option.descriptionstring or null
delivery.priceMoney or null
delivery.addressAddress or null
delivery.phonestring or null
delivery.instructionsstring or null
totalsobjectRely on total: what the next order charges. Do not add the parts up; where prices include tax it is already inside them.
totals.linesMoney or null
totals.deliveryMoney or null
totals.taxMoney or null
totals.totalMoney or null
totals.estimatedbooleanShopify has not yet projected the order with tax; total is lines plus delivery.
discountsarray of Discount
paymentMethodPayment method or null
paymentobject
payment.lastStatusstring or nullSUCCEEDED, FAILED…
payment.lastErrorTypestring or nullPAYMENT_ERROR, INVENTORY_ERROR, CUSTOMER_ERROR or OTHER.
payment.failingboolean
payment.nextRetryAtdate-time or null
pendingCancellationobject or nullAn end-of-cycle cancel not yet carried out.
pendingCancellation.effectiveAtdate-time
pendingCancellation.scheduledBystring or nullOne of customer, merchant, api.
pendingCancellation.reasonstring or null
originOrderobject or null
originOrder.idstring
originOrder.gidstring
originOrder.namestring or null
originOrder.createdAtdate-time or null
notestring or null
customAttributesarray of object
customAttributes[].keystring
customAttributes[].valuestring 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.

Scope subscriptions:read

ParameterInDescription
statusqueryOne of ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED.
customerIdqueryOne customer's subscriptions: a numeric id or gid.
limitqueryDefault 25.
cursorquerynextCursor 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)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
invalid_pagination400limit is not 1 to 100, or cursor is not one this API returned.
invalid_status400status is not a subscription status.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.

And the errors any request can get.

One subscription

GET /v1/subscriptions/{id}

Always every line, read from Shopify when there are more than 50.

Scope subscriptions:read

ParameterInDescription
id RequiredpathThe 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)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.

And the errors any request can get.

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:

FieldTypeDescription
subscriptionSubscription
notificationobject
notification.sentbooleanWhether the customer was emailed. False when not asked to, or when it could not be sent.
warningsarray of Warning
chargeobject
charge.statestringOne 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.

Scope subscriptions:write · Works while changes are paused

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
notifyCustomerbooleanEmail the customer about the change. Default false.
revisionIdstringOptional. 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)
CodeStatusMeaning
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_request400Something in the request is wrong; message says what and param names the field when there is one.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.
cancellation_scheduled409The subscription is already set to end.
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.
subscription_not_active409Only an active subscription can do this.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Resume

POST /v1/subscriptions/{id}/resume

The next charge is one interval from now.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
notifyCustomerbooleanEmail the customer about the change. Default false.
revisionIdstringOptional. 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)
CodeStatusMeaning
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_request400Something in the request is wrong; message says what and param names the field when there is one.
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.
subscription_not_found404No subscription with that id in this store.
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.
subscription_not_paused409The subscription is not paused.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
no_billing_interval422The subscription has no billing interval to resume on.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Cancel

POST /v1/subscriptions/{id}/cancel

Now, or at the end of the paid cycle (pendingCancellation until then).

Scope subscriptions:write · Works while changes are paused

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
when RequiredstringOne of immediate, endOfCycle.
revisionId RequiredstringThe revisionId the preview gave. Required: a price confirmed against one version must not be charged against another.
reasonIdstringOne of the store's cancellation reasons.
childIdstring
notestring
notifyCustomerbooleanEmail 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)
CodeStatusMeaning
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_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_when400when must be immediate or endOfCycle.
revision_id_required400This change is priced, so it needs the revisionId the price was given at.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.
cancellation_scheduled409The subscription is already set to end.
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.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
no_delivery_rates422Shopify has no delivery rates for that address.
no_upcoming_order422The subscription has no upcoming order.
subscription_closed422The subscription is cancelled or expired.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Keep a subscription set to end

POST /v1/subscriptions/{id}/cancel/withdraw

Calls off a pending end-of-cycle cancel, whoever scheduled it.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
notifyCustomerbooleanEmail the customer about the change. Default false.
revisionIdstringOptional. 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)
CodeStatusMeaning
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.
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.
subscription_not_found404No subscription with that id in this store.
cancellation_not_scheduled409The subscription is not set to end.
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.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
subscription_closed422The subscription is cancelled or expired.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

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.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
datedate
atdate-time
revisionIdstringOptional. 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)
CodeStatusMeaning
invalid_date400Not a valid date.
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.
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.
subscription_not_found404No subscription with that id in this store.
charge_in_progress409An order for this subscription is being charged now. Retry in a minute.
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.
body_too_large413The body is too large.
date_in_past422The new date is not in the future. To charge now, use ship-now.
idempotency_key_reused422The same Idempotency-Key with a different request.
subscription_closed422The subscription is cancelled or expired.

And the errors any request can get.

Where skipping would move the next charge

GET /v1/subscriptions/{id}/skip

Writes nothing.

Scope subscriptions:read

ParameterInDescription
id RequiredpathThe 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
FieldTypeDescription
previewobject
preview.allowedboolean
preview.reasonstring or nullThe error code the skip would answer.
preview.fromobject or null
preview.from.datedate
preview.from.atdate-time
preview.toobject or null
preview.to.datedate
preview.to.atdate-time
revisionIdstringSend it with the write.
Errors (3)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.

And the errors any request can get.

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.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
fromdate-timeThe nextBilling.at being skipped. Given, the skip is refused with schedule_changed if the date has moved.
revisionIdstringOptional. 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)
CodeStatusMeaning
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_request400Something in the request is wrong; message says what and param names the field when there is one.
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.
subscription_not_found404No subscription with that id in this store.
cancellation_scheduled409The subscription is already set to end.
charge_in_progress409An order for this subscription is being charged now. Retry in a minute.
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.
schedule_changed409The date of the order changed. Read the subscription and retry.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
no_upcoming_order422The subscription has no upcoming order.
prepaid_subscription422Not possible on a prepaid subscription.
subscription_closed422The subscription is cancelled or expired.
subscription_paused422The subscription is paused; resume it first.

And the errors any request can get.

Charge the next order now

POST /v1/subscriptions/{id}/ship-now

Charges now and moves the schedule on from today. Send an Idempotency-Key.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
revisionIdstringOptional. 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)
CodeStatusMeaning
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_request400Something in the request is wrong; message says what and param names the field when there is one.
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.
subscription_not_found404No subscription with that id in this store.
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.
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.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
no_delivery_rates422Shopify has no delivery rates for that address.
subscription_closed422The subscription is cancelled or expired.
subscription_paused422The subscription is paused; resume it first.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Items

Change quantities

POST /v1/subscriptions/{id}/quantities

Lines not listed are left alone.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
lines Requiredarray of object
lines[].id RequiredstringA line id from the subscription.
lines[].quantity Requiredinteger
revisionIdstringOptional. 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)
CodeStatusMeaning
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_request400Something in the request is wrong; message says what and param names the field when there is one.
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.
line_not_found404No line with that id on this subscription.
subscription_not_found404No subscription with that id in this store.
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.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
no_delivery_rates422Shopify has no delivery rates for that address.
subscription_closed422The subscription is cancelled or expired.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Price a line replacement

POST /v1/subscriptions/{id}/swap/preview

Writes nothing.

Scope subscriptions:write · Works while changes are paused

ParameterInDescription
id RequiredpathThe numeric id or the gid.
FieldTypeDescription
lineId RequiredstringA line id from the subscription.
variantId RequiredstringA product variant id or gid.
pricestringA decimal amount in the subscription's currency, such as "12.50". Leave it out to take the price the store's rules give.
quantityinteger
attachPlanbooleanPut 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
FieldTypeDescription
previewobject
preview.lineIdstring
preview.fromobject
preview.from.productobject or null
preview.from.product.idstring
preview.from.product.gidstring
preview.from.product.titlestring or null
preview.from.variantobject or null
preview.from.variant.idstring
preview.from.variant.gidstring
preview.from.variant.titlestring or null
preview.from.priceMoney or null
preview.from.basePriceMoney or null
preview.from.sellingPlanobject or null
preview.from.sellingPlan.idstring
preview.from.sellingPlan.gidstring
preview.from.sellingPlan.namestring or null
preview.toobject
preview.to.productobject or null
preview.to.product.idstring
preview.to.product.gidstring
preview.to.product.titlestring or null
preview.to.variantobject or null
preview.to.variant.idstring
preview.to.variant.gidstring
preview.to.variant.titlestring or null
preview.to.priceMoney or null
preview.to.basePriceMoney or null
preview.to.sellingPlanobject or null
preview.to.sellingPlan.idstring
preview.to.sellingPlan.gidstring
preview.to.sellingPlan.namestring or null
preview.quantityobject
preview.quantity.frominteger
preview.quantity.tointeger
preview.defaultPriceMoney or null
preview.priceSetByMerchantboolean
preview.customerCanSwapboolean
preview.warningsarray of Warning
revisionIdstringSend it with the write.
Errors (13)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
invalid_json400The body is not valid JSON.
invalid_price400A price is missing, negative or too large.
invalid_quantity400Quantity must be a whole number in the allowed range.
invalid_request400Something in the request is wrong; message says what and param names the field when there is one.
invalid_variant_id400Not a product variant id.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
line_not_found404No line with that id on this subscription.
subscription_not_found404No subscription with that id in this store.
body_too_large413The body is too large.
product_unavailable422The product is deleted or not active.
same_variant422That variant is already on this line.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Replace a line

POST /v1/subscriptions/{id}/swap

With the revisionId from the preview.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
lineId RequiredstringA line id from the subscription.
variantId RequiredstringA product variant id or gid.
pricestringA decimal amount in the subscription's currency, such as "12.50". Leave it out to take the price the store's rules give.
quantityinteger
attachPlanbooleanPut the new product on a selling plan at the subscription's frequency when it has one (the default).
revisionId RequiredstringThe 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)
CodeStatusMeaning
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_price400A price is missing, negative or too large.
invalid_quantity400Quantity must be a whole number in the allowed range.
invalid_request400Something in the request is wrong; message says what and param names the field when there is one.
invalid_variant_id400Not a product variant id.
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.
line_not_found404No line with that id on this subscription.
subscription_not_found404No subscription with that id in this store.
cancellation_scheduled409The subscription is already set to end.
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.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
no_delivery_rates422Shopify has no delivery rates for that address.
product_unavailable422The product is deleted or not active.
same_variant422That variant is already on this line.
subscription_closed422The subscription is cancelled or expired.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Price an added line

POST /v1/subscriptions/{id}/add/preview

Writes nothing.

Scope subscriptions:write · Works while changes are paused

ParameterInDescription
id RequiredpathThe numeric id or the gid.
FieldTypeDescription
variantId RequiredstringA product variant id or gid.
kindstringoneTime ships with the next order only and comes off after it is charged. One of recurring, oneTime. Default "recurring".
quantityinteger
pricestringA decimal amount in the subscription's currency, such as "12.50". Leave it out to take the price the store's rules give.
attachPlanbooleanPut 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
FieldTypeDescription
previewobject
preview.kindstringOne of recurring, oneTime.
preview.productobject or null
preview.product.idstring
preview.product.gidstring
preview.product.titlestring or null
preview.variantobject or null
preview.variant.idstring
preview.variant.gidstring
preview.variant.titlestring or null
preview.quantityinteger
preview.priceMoney or null
preview.basePriceMoney or null
preview.defaultPriceMoney or null
preview.priceSetByMerchantboolean
preview.sellingPlanNamestring or null
preview.customerCanSwapboolean
preview.discountsarray of object
preview.discounts[].codestring
preview.discounts[].appliesboolean
preview.warningsarray of Warning
revisionIdstringSend it with the write.
Errors (13)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
invalid_json400The body is not valid JSON.
invalid_kind400Choose whether the item renews or is for the next order only.
invalid_price400A price is missing, negative or too large.
invalid_quantity400Quantity must be a whole number in the allowed range.
invalid_request400Something in the request is wrong; message says what and param names the field when there is one.
invalid_variant_id400Not a product variant id.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.
body_too_large413The body is too large.
product_unavailable422The product is deleted or not active.
too_many_lines422The subscription has as many lines as it can hold.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

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.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
variantId RequiredstringA product variant id or gid.
kindstringoneTime ships with the next order only and comes off after it is charged. One of recurring, oneTime. Default "recurring".
quantityinteger
pricestringA decimal amount in the subscription's currency, such as "12.50". Leave it out to take the price the store's rules give.
attachPlanbooleanPut the new product on a selling plan at the subscription's frequency when it has one (the default).
revisionId RequiredstringThe 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)
CodeStatusMeaning
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_price400A price is missing, negative or too large.
invalid_quantity400Quantity must be a whole number in the allowed range.
invalid_request400Something in the request is wrong; message says what and param names the field when there is one.
invalid_variant_id400Not a product variant id.
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.
subscription_not_found404No subscription with that id in this store.
cancellation_scheduled409The subscription is already set to end.
conflict409The request conflicts with the state of the subscription; message says how.
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.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
no_delivery_rates422Shopify has no delivery rates for that address.
product_unavailable422The product is deleted or not active.
subscription_closed422The subscription is cancelled or expired.
too_many_lines422The subscription has as many lines as it can hold.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Check a line removal

POST /v1/subscriptions/{id}/remove-line/preview

Writes nothing.

Scope subscriptions:write · Works while changes are paused

ParameterInDescription
id RequiredpathThe numeric id or the gid.
FieldTypeDescription
lineId RequiredstringA 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
FieldTypeDescription
previewobject
preview.kindstringOne of recurring, oneTime.
preview.lastLinebooleanThe last renewing line cannot be removed; cancel instead.
preview.warningsarray of Warning
revisionIdstringSend it with the write.
Errors (6)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
invalid_json400The body is not valid JSON.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
line_not_found404No line with that id on this subscription.
subscription_not_found404No subscription with that id in this store.
body_too_large413The body is too large.

And the errors any request can get.

Remove a line

POST /v1/subscriptions/{id}/remove-line

The last renewing line is refused with last_line; cancel instead.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
lineId RequiredstringA line id from the subscription.
revisionId RequiredstringThe 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)
CodeStatusMeaning
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.
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.
line_not_found404No line with that id on this subscription.
subscription_not_found404No subscription with that id in this store.
cancellation_scheduled409The subscription is already set to end.
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.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
last_line422The subscription's last line cannot be removed; cancel instead.
no_delivery_rates422Shopify has no delivery rates for that address.
subscription_closed422The subscription is cancelled or expired.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Frequency

Frequencies it can move to

GET /v1/subscriptions/{id}/frequency-options

Each priced, line by line.

Scope subscriptions:read

ParameterInDescription
id RequiredpathThe 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
FieldTypeDescription
allowedboolean
reasonstring or null
currentobject or null
current.intervalstring
current.intervalCountinteger
optionsarray of object
options[].intervalstring
options[].intervalCountinteger
options[].linesarray of object
options[].lines[].lineIdstring
options[].lines[].fromobject
options[].lines[].from.sellingPlanNamestring or null
options[].lines[].from.priceMoney or null
options[].lines[].toobject
options[].lines[].to.sellingPlanNamestring or null
options[].lines[].to.priceMoney or null
options[].subtotalobject
options[].subtotal.fromMoney or null
options[].subtotal.toMoney or null
options[].priceChangedboolean
revisionIdstring or null
Errors (3)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.

And the errors any request can get.

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.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
interval RequiredstringOne of DAY, WEEK, MONTH, YEAR.
intervalCount Requiredinteger
revisionIdstringOptional. 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)
CodeStatusMeaning
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.
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.
subscription_not_found404No subscription with that id in this store.
cancellation_scheduled409The subscription is already set to end.
discount_running409A cancellation discount is running; change the frequency once it ends.
frequency_not_offered409That frequency is not offered for everything on the subscription.
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.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
no_delivery_rates422Shopify has no delivery rates for that address.
prepaid_subscription422Not possible on a prepaid subscription.
subscription_closed422The subscription is cancelled or expired.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Delivery address

Delivery options for an address

POST /v1/subscriptions/{id}/address/preview

The rates Shopify offers for the address. Writes nothing.

Scope subscriptions:write · Works while changes are paused

ParameterInDescription
id RequiredpathThe numeric id or the gid.
FieldTypeDescription
address RequiredobjectfirstName, lastName, company, address1, address2, city, province or provinceCode, zip, countryCode, phone.
address.firstNamestring
address.lastNamestring
address.companystring
address.address1string
address.address2string
address.citystring
address.provincestring
address.provinceCodestring
address.zipstring
address.countryCode Requiredstring
address.phonestring

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
FieldTypeDescription
previewobject
preview.addressAddress
preview.deliveryOptionsarray of object
preview.deliveryOptions[].codestring
preview.deliveryOptions[].titlestring or null
preview.deliveryOptions[].descriptionstring or null
preview.deliveryOptions[].priceMoney or null
preview.deliveryOptions[].phoneRequiredboolean
preview.currentOptionCodestring or null
preview.unchangedboolean
revisionIdstringSend it with the write.
Errors (11)
CodeStatusMeaning
country_required400The address needs a country.
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
invalid_json400The body is not valid JSON.
invalid_request400Something in the request is wrong; message says what and param names the field when there is one.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.
body_too_large413The body is too large.
country_not_shipped422The store does not ship to that country.
no_delivery_rates422Shopify has no delivery rates for that address.
not_shipped422The subscription is picked up or delivered locally, so it has no shipping address to change.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Change the delivery address

POST /v1/subscriptions/{id}/address

optionCode is one of the preview's deliveryOptions.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
address RequiredobjectfirstName, lastName, company, address1, address2, city, province or provinceCode, zip, countryCode, phone.
address.firstNamestring
address.lastNamestring
address.companystring
address.address1string
address.address2string
address.citystring
address.provincestring
address.provinceCodestring
address.zipstring
address.countryCode Requiredstring
address.phonestring
optionCode Requiredstring
revisionId RequiredstringThe 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)
CodeStatusMeaning
country_required400The address needs a country.
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_request400Something in the request is wrong; message says what and param names the field when there is one.
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.
subscription_not_found404No subscription with that id in this store.
delivery_option_unavailable409The delivery option chosen is no longer offered for that address. Preview again.
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.
body_too_large413The body is too large.
country_not_shipped422The store does not ship to that country.
idempotency_key_reused422The same Idempotency-Key with a different request.
no_delivery_rates422Shopify has no delivery rates for that address.
not_shipped422The subscription is picked up or delivered locally, so it has no shipping address to change.
subscription_closed422The subscription is cancelled or expired.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

Discount codes

Check a discount code

POST /v1/subscriptions/{id}/discounts/preview

Writes nothing.

Scope subscriptions:write · Works while changes are paused

ParameterInDescription
id RequiredpathThe numeric id or the gid.
FieldTypeDescription
code Requiredstring

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
FieldTypeDescription
previewobject
preview.codestring
preview.titlestring or null
preview.valueobject
preview.value.typestringOne of PERCENTAGE, FIXED_AMOUNT.
preview.value.percentagenumber
preview.value.amountMoney or null
preview.value.appliesOnEachItemboolean or null
preview.cycleLimitinteger or null
preview.lineIdsarray of string
preview.warningsarray of Warning
revisionIdstringSend it with the write.
Errors (16)
CodeStatusMeaning
discount_code_required400No code was sent.
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
invalid_json400The body is not valid JSON.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.
discount_already_applied409The code is already on this subscription.
discount_does_not_combine409The code does not combine with a discount already on the subscription.
body_too_large413The body is too large.
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.

And the errors any request can get.

Add a discount code

POST /v1/subscriptions/{id}/discounts

A Shopify discount code, applied as it would be at checkout.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
code Requiredstring
revisionId RequiredstringThe 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)
CodeStatusMeaning
discount_code_required400No code was sent.
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.
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.
subscription_not_found404No subscription with that id in this store.
cancellation_scheduled409The subscription is already set to end.
discount_already_applied409The code is already on this subscription.
discount_does_not_combine409The code does not combine with a discount already on the subscription.
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.
body_too_large413The body is too large.
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.
subscription_closed422The subscription is cancelled or expired.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

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.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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.
FieldTypeDescription
discountId Requiredstring
revisionId RequiredstringThe 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)
CodeStatusMeaning
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_request400Something in the request is wrong; message says what and param names the field when there is one.
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.
discount_not_found404No such discount on this subscription.
subscription_not_found404No subscription with that id in this store.
cancellation_scheduled409The subscription is already set to end.
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.
body_too_large413The body is too large.
discount_code_not_found422No discount with that code, or it has been deleted.
idempotency_key_reused422The same Idempotency-Key with a different request.
subscription_closed422The subscription is cancelled or expired.
unprocessable422The request is understood but cannot be carried out; message says why.

And the errors any request can get.

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.

Scope subscriptions:write

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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)
CodeStatusMeaning
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.
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.
subscription_not_found404No subscription with that id in this store.
request_in_progress409A request with this Idempotency-Key is still running.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.
payment_update_not_sendable422The email cannot be sent: no address, a suppressed address, or a payment method Shopify cannot send a link for.
subscription_closed422The subscription is cancelled or expired.
payment_update_recently_sent429An update email was sent moments ago. Try again in a few minutes.

And the errors any request can get.

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.

Scope subscriptions:write · Works while changes are paused

ParameterInDescription
id RequiredpathThe numeric id or the gid.
Idempotency-KeyheaderAny 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)
CodeStatusMeaning
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.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.
request_in_progress409A request with this Idempotency-Key is still running.
body_too_large413The body is too large.
idempotency_key_reused422The same Idempotency-Key with a different request.

And the errors any request can get.

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.

Scope subscriptions:read

ParameterInDescription
id RequiredpathThe numeric id or the gid.
limitqueryDefault 25.
cursorquerynextCursor 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)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
invalid_pagination400limit is not 1 to 100, or cursor is not one this API returned.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.

And the errors any request can get.

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.

Scope subscriptions:read

ParameterInDescription
id RequiredpathThe 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)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.

And the errors any request can get.

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.

Scope subscriptions:read

ParameterInDescription
id RequiredpathThe numeric id or the gid.
limitqueryDefault 25.
cursorquerynextCursor 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)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
invalid_pagination400limit is not 1 to 100, or cursor is not one this API returned.
insufficient_scope403The key lacks the scope this needs; requiredScope names it.
subscription_not_found404No subscription with that id in this store.

And the errors any request can get.

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.

FieldTypeDescription
codestringSee x-warning-codes.
messagestring
closesAtdate-time
deliveriesinteger
CodeMeaning
out_of_stockThe variant is out of stock.
no_selling_planThe product has no selling plan at this frequency, so the line goes on without one.
past_cutoffThe next order may already be being prepared (closesAt says when the cut-off was).
payment_recoveringA failed payment is being retried; the change alters the amount retried.
currency_mismatchThe subscription is billed in another currency than the store's.
customer_cannot_swapThe customer will not be able to swap this line themselves.
prepaidA prepaid line's price is the whole cycle's (deliveries says how many).
customer_already_usedThe customer has used this code before.
for_other_customersThe code is set for other customers.
for_customer_segmentsThe code is set for customer segments.
single_use_usedThe code is single-use and has been used.
other_discountsThe subscription has other discounts.
not_all_linesThe code covers only some of the lines.
otherSomething 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.

FieldTypeDescription
idstringA gid. Lines have no numeric id in Shopify.
productobject or nullNull once the product is deleted.
product.idstring
product.gidstring
product.titlestring or null
variantobject or null
variant.idstring
variant.gidstring
variant.titlestring or null
variant.skustring or null
quantityinteger
priceMoney or null
basePriceMoney or null
totalMoney or null
sellingPlanobject or nullNull for a line added without a plan.
sellingPlan.idstring
sellingPlan.gidstring
sellingPlan.namestring or null
priceSchedulearray of objectPrice changes after a number of cycles, such as a first-order discount.
priceSchedule[].afterCycleinteger
priceSchedule[].priceMoney or null
oneTimebooleanAn item for the next order only; it comes off after the next successful charge.
imageUrlstring 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

FieldTypeDescription
firstNamestring or null
lastNamestring or null
companystring or null
address1string or null
address2string or null
citystring or null
provincestring or null
provinceCodestring or null
zipstring or null
countrystring or null
countryCodestring or null
phonestring 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.

FieldTypeDescription
typestring or nullWEEKDAY, MONTHDAY or YEARDAY.
dayinteger or null
monthinteger or null
cutoffDayinteger or null
{
  "type": "MONTHDAY",
  "day": 1,
  "month": null,
  "cutoffDay": 5
}

The discount object

FieldTypeDescription
idstring
typestring or nullCODE_DISCOUNT, MANUAL or AUTOMATIC_DISCOUNT.
titlestring or null
codestring or nullThe code, on a CODE_DISCOUNT.
targetstring or nullLINE_ITEM or SHIPPING_LINE.
valueobject
value.typestringOne of PERCENTAGE, FIXED_AMOUNT.
value.percentagenumber
value.amountMoney or null
value.appliesOnEachItemboolean or null
cyclesUsedinteger or null
cycleLimitinteger or null
rejectedbooleanShopify 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.

FieldTypeDescription
typestringOTHER is a method Shopify added after this was written. One of CARD, SHOP_PAY, PAYPAL, BANK_ACCOUNT, OTHER.
brandstring or null
lastDigitsstring or null
expiryMonthinteger or null
expiryYearinteger or null
expiresSoonboolean
walletstring or nullapple_pay, google_pay… when the card came from one.
paypalEmailstring or null
inactiveboolean
revokedboolean
{
  "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.

FieldTypeDescription
idstring
gidstring
namestring or null
kindstringOne of firstOrder, renewal.
createdAtdate-time or null
cancelledAtdate-time or null
financialStatusstring or null
fulfillmentStatusstring or null
totalMoney 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.

FieldTypeDescription
idstring
actorobject
actor.kindstringOne of customer, merchant, api.
actor.namestring or null
startedAtdate-time or null
completedAtdate-time or null
outcomestring or nullNull while in the flow, or when the customer left it. One of cancelled, scheduled, saved, withdrawn.
whenstring or nullOne of immediate, endOfCycle, split.
effectiveAtdate-time or null
reasonstring or null
followUpstring or null
notestring or null
offerobject or null
offer.kindstring or null
offer.outcomestring or nullOne of accepted, declined.
offer.discountPercentnumber or null
offer.ordersinteger or null
offer.delayDaysinteger 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
  }
}