Developers
Customers & activity
Read your customers, follow everything that happens on your store through its activity, and see each charge Vanix made or tried.
| Endpoint | What it does |
|---|---|
GET /v1/customers | List customers |
GET /v1/customers/{id} | One customer |
GET /v1/customers/{id}/activity | A customer's activity |
GET /v1/activity | The store's activity |
GET /v1/billing-runs | Charges |
The customer object
Shopify's customer record, with a summary of their subscriptions. Customers are read from Shopify as you ask for them, and can't be changed through the API. A list has the fields down to subscriptions; reading one customer adds the rest. Their subscriptions themselves are GET /v1/subscriptions?customerId=.
| Field | Type | Description |
|---|---|---|
id | string | |
gid | string | |
displayName | string or null | |
firstName | string or null | |
lastName | string or null | |
email | string or null | |
phone | string or null | |
createdAt | date-time or null | |
numberOfOrders | integer | |
amountSpent | Money or null | |
subscriptions | object | |
subscriptions.count | integer | |
subscriptions.status | string or null | The one that matters most when there are several: FAILED, then ACTIVE, PAUSED, CANCELLED, EXPIRED. |
updatedAt | date-time or null | |
note | string or null | |
tags | array of string | |
verifiedEmail | boolean | |
marketingState | string or null | |
defaultAddress | object or null | |
defaultAddress.address1 | string or null | |
defaultAddress.address2 | string or null | |
defaultAddress.city | string or null | |
defaultAddress.province | string or null | |
defaultAddress.zip | string or null | |
defaultAddress.country | string or null | |
defaultAddress.phone | string or null | |
lastOrder | object or null | |
lastOrder.id | string | |
lastOrder.gid | string | |
lastOrder.name | string or null | |
lastOrder.createdAt | date-time or null | |
lastOrder.total | Money or null |
{
"id": "7712345678901",
"gid": "gid://shopify/Customer/7712345678901",
"displayName": "Jane Doe",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@example.com",
"phone": "+15035550123",
"createdAt": "2026-03-02T19:20:44Z",
"numberOfOrders": 4,
"amountSpent": {
"amount": "104.40",
"currencyCode": "USD"
},
"subscriptions": {
"count": 1,
"status": "ACTIVE"
},
"updatedAt": "2026-10-14T16:00:05Z",
"note": null,
"tags": ["VIP"],
"verifiedEmail": true,
"marketingState": "SUBSCRIBED",
"defaultAddress": {
"address1": "12 Harbour Street",
"address2": null,
"city": "Portland",
"province": "Oregon",
"zip": "97201",
"country": "United States",
"phone": "+15035550123"
},
"lastOrder": {
"id": "6012345678901",
"gid": "gid://shopify/Order/6012345678901",
"name": "#1042",
"createdAt": "2026-10-14T16:00:04Z",
"total": {
"amount": "26.60",
"currencyCode": "USD"
}
}
}Customers
These need customers:read.
List customers
GET /v1/customers
Read live from Shopify, sorted by name, or by relevance with query.
| Parameter | In | Description |
|---|---|---|
query | query | Shopify's customer search syntax. A bare term matches name, email and phone. |
limit | query | Default 25. |
cursor | query | nextCursor from the previous page. |
Request
curl "https://api.vanixcommerce.com/v1/customers?query=jane" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"data": [
{
"id": "7712345678901",
"gid": "gid://shopify/Customer/7712345678901",
"displayName": "Jane Doe",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@example.com",
"phone": "+15035550123",
"createdAt": "2026-03-02T19:20:44Z",
"numberOfOrders": 4,
"amountSpent": {
"amount": "104.40",
"currencyCode": "USD"
},
"subscriptions": {
"count": 1,
"status": "ACTIVE"
}
}
],
"nextCursor": null
}Errors (2)
| Code | Status | Meaning |
|---|---|---|
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. |
One customer
GET /v1/customers/{id}
Shopify's record, with a summary of their subscriptions. The subscriptions themselves are GET /subscriptions?customerId=.
| Parameter | In | Description |
|---|---|---|
id Required | path | The numeric id or the gid. |
Request
curl "https://api.vanixcommerce.com/v1/customers/7712345678901" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"customer": { "id": "7712345678901", "gid": "gid://shopify/Customer/7712345678901", … }
}Errors (4)
| Code | Status | Meaning |
|---|---|---|
invalid_id | 400 | An id that is neither a numeric id nor a gid of the right kind. |
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. |
customer_not_found | 404 | No customer with that id in this store. |
A customer's activity
GET /v1/customers/{id}/activity
Across all their subscriptions, newest first.
| 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/customers/7712345678901/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 (3)
| 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. |
Activity
Everything that happens to your subscriptions, as events, newest first: changes made by customers, your staff and API keys, charges, and billing recovery. To keep another system up to date, read the activity from where you last stopped. The activity of one subscription is on Subscriptions.
The event object
An event's id never changes, so you can use it to skip events you've already handled. actor.kind is who made it happen: customer, merchant for your staff, api for a key (with the key's name in actor.name), or system for Vanix itself, such as a renewal.
| Field | Type | Description |
|---|---|---|
id | string | The same id a webhook for this event will carry; dedupe on it. |
topic | string | See x-topics. |
occurredAt | date-time | |
subscription | Ref or null | |
customer | Ref or null | |
actor | object | |
actor.kind | string | One of customer, merchant, api, system. |
actor.name | string or null | The API key's name, for api. |
details | object | The event's own data, per topic (x-topics). Fields may be added. |
{
"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"
}
}Topics
Each event's topic is one of these, and details holds the fields listed for it. Topics and fields may be added, so ignore ones you don't know.
| Topic | When | Details |
|---|---|---|
charge.action_required | The customer has to act, such as a 3-D Secure check. | actionStatus |
charge.failed | A charge was declined or failed. | errorCode, errorMessage, amountAttempted |
charge.succeeded | A charge made an order. | order, amount |
discount.deactivated | A Shopify discount code was used up and deactivated. | title, usageLimit |
payment_method.revoked | The customer's payment method was revoked. | none |
recovery.halted | Retries ran out. action is what the store's recovery settings did: cancel, pause, or null when the subscription is left as it is. | reason, attempts, action |
recovery.recovered | A retried charge went through. | attempts |
recovery.retry_scheduled | A failed charge will be retried. | reason, attempt, of, retryAt |
subscription.activated | Became active other than by resuming, such as a failed subscription charged again. | from, to |
subscription.address_changed | The delivery address changed. | changed: the fields that did |
subscription.cancellation_scheduled | Set to end at the end of the paid cycle. | effectiveAt, reason |
subscription.cancellation_withdrawn | A subscription set to end was kept. | wasEndingAt |
subscription.cancelled | Cancelled through Vanix: now, or at the end of the cycle it was set to end on. A cancel by recovery, once retries run out, is recovery.halted with action: "cancel" instead. | when, effectiveAt, reason |
subscription.created | A subscription was created, at checkout or otherwise. | status |
subscription.discounts_changed | A discount started or ended. | change (offerStarted, offerEnded, codeAdded, codeEnded, codeSwapped), code, reason |
subscription.expired | Reached its last cycle. | from, to |
subscription.failed | Shopify marked it failed. | from, to |
subscription.frequency_changed | The delivery frequency changed. | from, to |
subscription.lines_changed | Lines changed. | change: quantities, swapped, replaced, added, removed or oneTimeRemoved |
subscription.paused | Paused, by anyone. | from, to |
subscription.rescheduled | The next charge moved: by a person, ship-now, a resume, or a charge (reason). | from, to, reason |
subscription.resumed | Resumed from paused. | from, to |
subscription.saved | A cancellation offer kept the customer. | offerKind |
subscription.skipped | The next order was skipped. | from, to |
The store's activity
GET /v1/activity
Every published event, newest first.
| Parameter | In | Description |
|---|---|---|
limit | query | Default 25. |
cursor | query | nextCursor from the previous page. |
Request
curl "https://api.vanixcommerce.com/v1/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 (2)
| Code | Status | Meaning |
|---|---|---|
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. |
Billing runs
Each charge Vanix made or tried for a renewal, a retry or a ship now, newest first. These need subscriptions:read.
The billing run object
| Field | Type | Description |
|---|---|---|
id | string | |
subscription | Ref | |
dueAt | date-time | |
state | string | One of SUCCEEDED, FAILED, ACTION_REQUIRED, PENDING, RETRYING, CANCELLED, WITHDRAWN. |
attempts | integer | |
createdAt | date-time | |
settledAt | date-time or null | |
order | object or null | |
order.id | string | |
order.gid | string | |
order.name | string or null | |
amount | Money or null | |
error | object or null | |
error.code | string or null | |
error.message | string or null |
{
"id": "6713f0c2a4b5d6e7f8091a2b",
"subscription": {
"id": "26893631718",
"gid": "gid://shopify/SubscriptionContract/26893631718"
},
"dueAt": "2026-10-14T16:00:00Z",
"state": "SUCCEEDED",
"attempts": 1,
"createdAt": "2026-10-14T16:00:01Z",
"settledAt": "2026-10-14T16:00:04Z",
"order": {
"id": "6012345678901",
"gid": "gid://shopify/Order/6012345678901",
"name": "#1042"
},
"amount": {
"amount": "26.60",
"currencyCode": "USD"
},
"error": null
}Charges
GET /v1/billing-runs
Each charge we made or tried, newest first.
| Parameter | In | Description |
|---|---|---|
subscriptionId | query | One subscription's: an id or gid. |
limit | query | Default 25. |
cursor | query | nextCursor from the previous page. |
Request
curl "https://api.vanixcommerce.com/v1/billing-runs?subscriptionId=26893631718" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"data": [
{
"id": "6713f0c2a4b5d6e7f8091a2b",
"subscription": {
"id": "26893631718",
"gid": "gid://shopify/SubscriptionContract/26893631718"
},
"dueAt": "2026-10-14T16:00:00Z",
"state": "SUCCEEDED",
"attempts": 1,
"createdAt": "2026-10-14T16:00:01Z",
"settledAt": "2026-10-14T16:00:04Z",
"order": {
"id": "6012345678901",
"gid": "gid://shopify/Order/6012345678901",
"name": "#1042"
},
"amount": {
"amount": "26.60",
"currencyCode": "USD"
},
"error": null
}
],
"nextCursor": null
}Errors (3)
| 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. |