Developers

API overview

The Vanix API lets your own systems read and change your subscriptions. A warehouse system can pause a subscription when an item runs out, a help desk can show a customer's subscriptions beside their ticket, and a script can move every next order after a holiday.

It does what your staff can do in Vanix, under the same rules. A change made through the API is checked and priced the same way, appears in the subscription's activity as made By API key with the key's name, and only emails the customer when you ask it to. The API is included on every Vanix plan, with the same limits on each.

What it covers

AreaWhat you can do
SubscriptionsRead them, and make every change your staff can: pause, resume, cancel, move or skip the next order, ship now, change quantities, swap, add and remove items, change the frequency and the delivery address, add and remove discount codes, and email the customer a link to update their payment method. Subscriptions
HistoryEach subscription's orders, cancellation attempts and activity. History
CustomersRead your customers, with a summary of their subscriptions, and their activity. Customers & activity
ActivityEvery event on your store, newest first, to keep another system up to date. Activity
Billing runsEach charge Vanix made or tried, and how it went. Billing runs

Base URL

https://api.vanixcommerce.com/v1

Every request is made over HTTPS, and sends and answers JSON. Paths in these docs start from /v1.

Your first request

  1. Create an API key

    In Vanix, go to Settings, then API keys, and choose Create API key. Copy the key when it's shown: it's shown only once. API keys & authentication

  2. Check it works

    Keep the key in an environment variable rather than in your code, then ask for your store:

    curl "https://api.vanixcommerce.com/v1/shop" \
      -H "Authorization: Bearer $VANIX_API_KEY"
    {
      "shop": {
        "domain": "example.myshopify.com",
        "timeZone": "America/Denver",
        "plan": {
          "handle": "growth",
          "name": "Growth"
        },
        "currencyCode": "USD",
        "taxesIncluded": false
      },
      "apiKey": {
        "id": "3f6c2b1e-8d4a-4c7e-9f1a-2b3c4d5e6f70",
        "name": "Warehouse sync",
        "prefix": "vx_live_4f9Q",
        "scopes": ["subscriptions:read", "customers:read"]
      },
      "environment": "live"
    }
  3. Read your subscriptions

    With a key that can read subscriptions:

    curl "https://api.vanixcommerce.com/v1/subscriptions?status=ACTIVE" \
      -H "Authorization: Bearer $VANIX_API_KEY"

    Each answer is a page of subscriptions. Reading the next page

Versioning

The version is in the path. Within /v1, changes only add things: new endpoints, new optional fields in requests, and new fields in answers. Write your code to ignore fields it doesn't know. A change that could break your code would come as /v2, and /v1 would keep working for at least 12 months after it.

OpenAPI file

The whole API is described in one OpenAPI 3.1 file, the same one these pages are built from. Load it into Postman or Insomnia to try requests, or into a code generator to make a client in your language.

Changelog

  • v1: the first release. Subscriptions and every change to them, their orders, cancellation attempts and activity; customers; the store's activity; and billing runs.