Developers

Customers & activity

Read your customers, follow everything that happens on your store through its activity, and see each charge Vanix made or tried.

EndpointWhat it does
GET /v1/customersList customers
GET /v1/customers/{id}One customer
GET /v1/customers/{id}/activityA customer's activity
GET /v1/activityThe store's activity
GET /v1/billing-runsCharges

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=.

FieldTypeDescription
idstring
gidstring
displayNamestring or null
firstNamestring or null
lastNamestring or null
emailstring or null
phonestring or null
createdAtdate-time or null
numberOfOrdersinteger
amountSpentMoney or null
subscriptionsobject
subscriptions.countinteger
subscriptions.statusstring or nullThe one that matters most when there are several: FAILED, then ACTIVE, PAUSED, CANCELLED, EXPIRED.
updatedAtdate-time or null
notestring or null
tagsarray of string
verifiedEmailboolean
marketingStatestring or null
defaultAddressobject or null
defaultAddress.address1string or null
defaultAddress.address2string or null
defaultAddress.citystring or null
defaultAddress.provincestring or null
defaultAddress.zipstring or null
defaultAddress.countrystring or null
defaultAddress.phonestring or null
lastOrderobject or null
lastOrder.idstring
lastOrder.gidstring
lastOrder.namestring or null
lastOrder.createdAtdate-time or null
lastOrder.totalMoney 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.

Scope customers:read

ParameterInDescription
queryqueryShopify's customer search syntax. A bare term matches name, email and phone.
limitqueryDefault 25.
cursorquerynextCursor 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)
CodeStatusMeaning
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.

And the errors any request can get.

One customer

GET /v1/customers/{id}

Shopify's record, with a summary of their subscriptions. The subscriptions themselves are GET /subscriptions?customerId=.

Scope customers:read

ParameterInDescription
id RequiredpathThe 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)
CodeStatusMeaning
invalid_id400An id that is neither a numeric id nor a gid of the right kind.
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.
customer_not_found404No customer with that id in this store.

And the errors any request can get.

A customer's activity

GET /v1/customers/{id}/activity

Across all their subscriptions, newest first.

Scope customers:read

ParameterInDescription
id RequiredpathThe numeric id or the gid.
limitqueryDefault 25.
cursorquerynextCursor 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)
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.

And the errors any request can get.

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.

FieldTypeDescription
idstringThe same id a webhook for this event will carry; dedupe on it.
topicstringSee x-topics.
occurredAtdate-time
subscriptionRef or null
customerRef or null
actorobject
actor.kindstringOne of customer, merchant, api, system.
actor.namestring or nullThe API key's name, for api.
detailsobjectThe 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.

TopicWhenDetails
charge.action_requiredThe customer has to act, such as a 3-D Secure check.actionStatus
charge.failedA charge was declined or failed.errorCode, errorMessage, amountAttempted
charge.succeededA charge made an order.order, amount
discount.deactivatedA Shopify discount code was used up and deactivated.title, usageLimit
payment_method.revokedThe customer's payment method was revoked.none
recovery.haltedRetries 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.recoveredA retried charge went through.attempts
recovery.retry_scheduledA failed charge will be retried.reason, attempt, of, retryAt
subscription.activatedBecame active other than by resuming, such as a failed subscription charged again.from, to
subscription.address_changedThe delivery address changed.changed: the fields that did
subscription.cancellation_scheduledSet to end at the end of the paid cycle.effectiveAt, reason
subscription.cancellation_withdrawnA subscription set to end was kept.wasEndingAt
subscription.cancelledCancelled 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.createdA subscription was created, at checkout or otherwise.status
subscription.discounts_changedA discount started or ended.change (offerStarted, offerEnded, codeAdded, codeEnded, codeSwapped), code, reason
subscription.expiredReached its last cycle.from, to
subscription.failedShopify marked it failed.from, to
subscription.frequency_changedThe delivery frequency changed.from, to
subscription.lines_changedLines changed.change: quantities, swapped, replaced, added, removed or oneTimeRemoved
subscription.pausedPaused, by anyone.from, to
subscription.rescheduledThe next charge moved: by a person, ship-now, a resume, or a charge (reason).from, to, reason
subscription.resumedResumed from paused.from, to
subscription.savedA cancellation offer kept the customer.offerKind
subscription.skippedThe next order was skipped.from, to

The store's activity

GET /v1/activity

Every published event, newest first.

Scope subscriptions:read

ParameterInDescription
limitqueryDefault 25.
cursorquerynextCursor 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)
CodeStatusMeaning
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.

And the errors any request can get.

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

FieldTypeDescription
idstring
subscriptionRef
dueAtdate-time
statestringOne of SUCCEEDED, FAILED, ACTION_REQUIRED, PENDING, RETRYING, CANCELLED, WITHDRAWN.
attemptsinteger
createdAtdate-time
settledAtdate-time or null
orderobject or null
order.idstring
order.gidstring
order.namestring or null
amountMoney or null
errorobject or null
error.codestring or null
error.messagestring 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.

Scope subscriptions:read

ParameterInDescription
subscriptionIdqueryOne subscription's: an id or gid.
limitqueryDefault 25.
cursorquerynextCursor 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)
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.

And the errors any request can get.