REST API V2

 API Updates for November 1st 2024

Due to new Shopify API limitations it is no longer possible to get the page_count or the total_count in the GET /customers response.

Migrating from REST API V1?

The biggest changes between V1 and V2 are:

  • API paths should point to /v2/ instead of /v1/
  • For paginating through results, the next_page value is no longer a simple number, but a cursor string.
  • To paginate through results pass ?next_page=[cursor from previous response]
  • Some available filters and options have changed to reflect Shopify API changes.

Heads Up!

The API is only available on our Plus plan.

The REST API allows you to make JSON-based API requests to get customer data, update customer data, and create new customers.

The API has a limit of 1 API call per second, largely because of Shopify's own API limits.

Some API calls allow you to do multiple actions at once, such as updating up to 10 customer records at a time.

Getting your API Key

The first step is getting your shop domain and API key from the API Key page. You can read more about that in the API Key Guide.

Authentication

The API requires two header values for authentication. These are provided to you on the API Key page. Your request should contain two custom header values:

x-shop-domain: your-domain.myshopify.com

x-api-key: your_api_key

REST API Endpoint

This is base API URL used to make API calls:

https://apps.bonify.io/apps/cf_app/public-api/customer_fields/v2/...

Responses

All API requests will return a JSON response, a "status" field, and an HTTP status code. Successful response will always return a 200 HTTP status code, and a "status" value of "okay".

An example error response when the API Key is incorrect:

Header (Status: 403 Forbidden)
{
  "status": "error",
  "message": "invalid request"
}

All error responses will include a "message" field with some additional information as to why the request was rejected.

An example success response when creating a new customer: 

Header (Status: 200 OK)
{
  "status": "okay"
}

GET /customers

Returns an array of customer objects with  customer_fields representing the custom fields you created. A max of 50 results can be returned at a time.

Example response:

{
  "status": "okay",
  "next_page": "eyJsYXN0X2lkIjo1MTAxMDABCTA5MDY0LCJsYXN0X3ZhbHVlIjoxNjE3ODk5NDABCAwLCJkaXJlY3Rpb24iABCuZXh0123",
  "customers": [
    {
      "id": 345345345345,
      "email": "apps+345@bonify.io",
      "first_name": "FNAME",
      "last_name": "LNAME",
      "customer_fields": [
        {
          "machine_name": "radios",
          "label": "Radios",
          "value": "one",
          "created_at": 1536680687,
          "updated_at": 1536680687
        },
        {
          "machine_name": "text",
          "label": "Text",
          "value": "Value for my custom text field.",
          "created_at": 1536167693,
          "updated_at": 1536343123
        }
      ]
    }
  ]
}

There are some special fields returned with additional information about the query:

prev_page: Pointer to the previous page.

next_page: Pointer to the next page to get. If not present, there are no more pages.

GET Query Params

There are special query params you can pass to GET requests, these include:

next_page: Specify the page you want to return.

filters: Provide a list of filters to search customer records by.

GET Filters Query Parameter

The filters query parameter makes it easy to search customer records by Shopify attributes, and also custom field attributes.

Available filter fields can be found in the Shopify REST API customers/search documentation.

Note: Supported filter fields (2022-10):

accepts_marketing, activation_date, address1, address2, city, company, country, customer_date, customer_first_name, customer_id, customer_last_name, customer_tag, email, email_marketing_state, first_name, first_order_date, id, last_abandoned_order_date, last_name, multipass_identifier, orders_count, order_date, phone, province, shop_id, state, tag, total_spent, updated_at, verified_email, product_subscriber_status

Multiple filters are provided in a comma-delimited query string in the following format:

?filters=field|operator|value,field2|operator|value,field3|operator|value

A real example would be:

?filters=email|contains|bonify
?filters=email|equals|bob@example.com
?filters=email|equals|"bob@example.com" <- You may want quotes for exact matches.

Available operators include (note that not all operators available for all field types):

contains: The string must contain this value.

not_contains: The string must not contain this value.

empty: Value is empty.

not_empty: Value is not empty.

equals: Value is equal to.

not_equals: Value is not equal to.

gt: Value is greater than.

lt: Value is less than.

When no results are found for a filtered query you will receive a response that looks like:

Header (Status: 200 OK)  
{      
  "status": "okay",
  "customers": [] 
}

GET /customers/{customer_id}

You can fetch a single customer by adding the customer ID to the end of the API URL. The response will match the default /customers API call.

PUT /customers

Updates customer records. PUT calls must be a JSON object with a "customers" array field. Customers should have an ID to key from. Example:

{
  "customers": [
    {
      "id": 123123123123,
      "last_name": "Update last name",
      "customer_fields": {
        "text": "updated custom field value.",
        "radios": "one"
      }
    }
  ]
}

This API call will update the customer's last name and two custom fields: "text" and "radios". All successful PUT requests will return:

Header (Status: 200 OK)  
{    
  "status": "okay" 
}

You can only update 10 customer records in a single API call.

To delete customer metafields using a PUT request you must set an additional header in the request:

x-delete-empty-metafields: true

You will then be able to pass an empty string or null value to a metafield and have it delete. Example where "text" metafield will get deleted:

{
  "customers": [
    {
      "id": 123123123123,
      "customer_fields": {
        "text": ""
      }
    }
  ]
}

Please note that each metafield deletion requires an API call to Shopify and deleting too many metafields at one time may cause you to hit API limit errors.

POST /customers

Creates new customers. This is very similar to the PUT request. You must provide a JSON object with a "customers" array field. Customers should not have IDs, but should have any other required fields you need, such as first_name, last_name, and email.

DELETE /customers/{customer_id}

Deletes a single customer. Does not require a POST body.

API Limits

If your app performs more than 1 API request per second you will receive the following response:

Header (Status: 429 Too Many Requests)  
{    
  "status": "error",
  "message": "too many requests"  
}

We suggest artificially slowing down your app's API calls if you are performing many operations.

If you attempt to update or create more than 10 customer records at a time you will receive: 

Header (Status: 400 Bad Request)  
{
  "status": "error",
  "message": "unable to update more than 10 customers at one time"
}

Related Articles