Link

REST API


Notice!

These docs don’t work with the new data columns model. As we’re working on a V2 implementation of our API, you’ll need to create fields under the legacy fields editor instead.


Overview

There may be cases where you want to update customer information within your own custom app. We have several API endpoints that allow you to manage unique customer data. Any information you save via the API will also be pushed directly via the Shopify API. We save custom fields in both our database and Shopify Metafields.

API Rate Limits

We limit requests similar to Shopify, which is 2 requests per second. We do not currently support Shopify’s similar “leaky bucket algorithm” with batch requests. If you exceed 2 requests per second at any time, you’ll receive a 429 “Too Many Requests” response.

Authentication

You can create an API token in the account tab. Any token has full access to any API endpoint. To authenticate, include the Authorization header in your request with the API token attached. It’s important to keep these keys safe, as anyone with access to this token has full access to your customer’s information.

Header Value
Authorization Token token="xxx"

Example curl request with authorization:

curl https://customr.heliumdev.com/api/v1/customers/5725212430 --header "Authorization: Token token="xxx""

Data

You may send data as either form data or JSON. Set the following header when posting data that is in JSON format:

Header Value
Content-Type application/json
Accept application/json

Endpoints

Create a new customer

POST /api/v1/customers
Parameters
field

string | number

Any parameter accepted by Customer from Shopify's API and any custom fields setup the fields section. Custom fields are referenced by a field's key. Keys are case sensitive.

validate

string (default: "true")

Turn off required field validations for custom fields.

Request

POST https://customr.heliumdev.com/api/v1/customers

{
  "customer": {
    "first_name": "Samwise",
    "last_name": "Gamgee",
    "email": "sam@lotr.net",
    "quote": "Don't you leave him Samwise Gamgee.",
    "birthday": "02/14/500",
    "addresses": [
      {
        "address1": "4563 Grass Ln",
        "province": "The Shire",
        "zip": 852156,
        "country": "Middle Earth"
      }
    ]
  }
}
Response
{
  "customer": {
    "id": 6725212430,
    "email": "sam@lotr.net",
    "accepts_marketing": false,
    "created_at": "2017-03-10T18:09:51-05:00",
    "updated_at": "2017-03-10T18:09:51-05:00",
    "first_name": "Samwise",
    "last_name": "Gamgee",
    "quote": "Don't you leave him Samwise Gamgee.",
    "birthday": "02/14/500",
    "orders_count": 0,
    "state": "disabled",
    "total_spent": 0,
    "last_order_id": null,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": null,
    "tags": "",
    "last_order_name": null,
    "domain": "example.myshopify.com",
    "addresses": [
      {
        "address1": "4563 Grass Ln",
        "province": "The Shire",
        "zip": 852156,
        "country": "Middle Earth"
      }
    ]
  }
}

Get a single customer

GET /api/v1/customers/:id
Parameters None
Request GET https://customr.heliumdev.com/api/v1/customers/5725212430
Response
{
  "customer": {
    "id": 5725212430,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.net",
    "custom_field_key": "Set this up in fields",
    "accepts_marketing": false,
    "created_at": "2017-03-10T18:09:51-05:00",
    "updated_at": "2017-03-10T18:09:51-05:00",
    "orders_count": 0,
    "state": "disabled",
    "total_spent": 0,
    "last_order_id": null,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": null,
    "tags": "",
    "last_order_name": null,
    "domain": "example.myshopify.com",
    "addresses": [
      {
        "company": "Hoeger Inc",
        "address1": "Rylan Wells",
        "address2": "Apt. 436",
        "city": "Port Nick",
        "province": null,
        "country": "United States",
        "zip": "72736",
        "phone": "570-020-0869"
      }
    ]
  }
}

Update a single customer

PUT /api/v1/customers/:id
Parameters
field

string | number

Any parameter accepted by Customer from Shopify's API and any custom fields setup the fields section. Custom fields are referenced by a field's key. Keys are case sensitive.

validate

string (default: "true")

Turn off required field validations for custom fields.

Request

PUT https://customr.heliumdev.com/api/v1/customers/3818644165

{
  customer: {
    first_name: "Jim",
    last_name: "Smith",
    favorite_color: "Green"
  }
}
Response
{
  "customer": {
    "id": 3818644165,
    "first_name": "Jim",
    "last_name": "Smith",
    "favorite_color": "Green",
    "email": "jim@example.net",
    "accepts_marketing": false,
    "created_at": "2017-03-10T18:09:51-05:00",
    "updated_at": "2017-03-10T18:09:51-05:00",
    "orders_count": 0,
    "state": "disabled",
    "total_spent": 0,
    "last_order_id": null,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": null,
    "tags": "",
    "last_order_name": null,
    "domain": "example.myshopify.com"
  }
}