REST API


There may be cases where you want to update customer information within your own custom app. We have several API endpoint 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

boolean (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/3818644165
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

boolean (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": 3725212430,
    "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"
  }
}