REST API V1 (deprecated)
Deprecated
Version 1 is now deprecated. Please see the V2 version of the docs.
Heads Up!
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/v1/...
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",
"page_count": 17,
"total_count": 801,
"next_page": 2,
"customers": [
{
"id": 345345345345,
"email": "apps+345@bonify.io",
"first_name": "FNAME",
"last_name": "LNAME",
... // More Shopify fields hidden.
"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
}
]
},
... // Max of 50 customers returned at once.
] }
There are some special fields returned with additional information about the query:
page_count: Total number of pages to navigate through.
total_count: Total number of records that the query has.
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:
page: Specify the page you want to return. Default is 1.
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. 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,tags|contains|awesome,custom_age_field|gt|18
Valid field filter operators include:
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",
"page_count": 0,
"total_count": 0,
"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"
}