Cartfunnel’s REST API follows RESTful conventions and utilizes the four commonly accepted request verbs for managing resources:
- GET
- POST
- PATCH
- DELETE
The format in which requests are received and responses are returned is in application/json or text/json.
Getting started
All requests should be made to the following endpoint:
https://api.cartfunnel.net/v1
Every request needs to be authenticated by adding the following headers into your request:
- X-CARTFUNNEL-ACCOUNT
- X-CARTFUNNEL-API-SECRET
X-CARTFUNNEL-ACCOUNT should be set as the value of your Cartfunnel subdomain. For example, if your Cartfunnel account lives at https://myshop.cartfunnel.net, the value should be “myshop”.
X-CARTFUNNEL-API-SECRET is a generated API secret that you create within the Cartfunnel dashboard. Go to Integrations and click on API, and then click on Create API secret.

You can customize the permission level for each individual API secret on the next page.
Remember: Do not share your API secret with any developer or third-party application that you do not trust. Treat your API secret safe!
API terminology
For those of you who are familiar with REST APIs, the following terminology should be familiar.
Each endpoint is what we call a Resource. For example, the Customer resource lives at /customers. The Product resource is found at /products.
An API call is referred to as a request. Each request must be made with a GET, POST, PATCH, or DELETE. These are called verbs. A GET request is made to retrieve a resource. A POST or a PATCH request is made to create or update a resource. Finally, a DELETE request is for destroying a resource. Not all verbs are available for all resources.
Handling errors
Successful API calls will return a 2xx HTTP return code. Note that a 200-level code is returned even in instances where an object is not saved, such as during a POST or PATCH request. To enable you to be able to quickly identify improperly saved objects, please examine the following:
- Each resource object will have a “persisted” attribute. If it is set to “true”, that means the new object is saved. If it is set to “false”, it is not saved.
- When saving a new or existing object, check for the “errors” attribute. Problems with saving the object will result in the presence of the “errors” attribute, which is an array of error messages. Successful saves will not return an “errors” attribute in the object.
Unsuccessful API calls will return a 403 code. Examples of unsuccessful calls include:
- Wrong authentication credentials
- API calls that are outside the permitted scopes (as set in the dashboard)
Customers resource
The Customers resource enables you to:
- List all your customers
- View the details of a single customer
- Create a new customer
- Update an existing customer
A customer object looks like this:
{
"id": 1,
"email": "[email protected]",
"created_at": "2018-12-04T23:29:37.406-05:00",
"updated_at": "2018-12-04T23:29:37.406-05:00",
"accepts_marketing": "true",
"first_name": "Joe",
"last_name": "El",
"note": "Special user",
"orders_count": 3,
"total_spent_cents": 100000,
"tax_exempt": "false",
"subscriptions_count": 1,
"last_order_id": 3200291,
"persisted": "true"
}
Properties
Attribute | Type | Notes |
string | required, on new records only | |
first_name | string | optional |
last_name | string | optional |
note | string | optional |
tax_exempt | boolean | defaults to false |
accepts_marketing | boolean | defaults to false |
tag_list | string | optional, comma delimited string |
GET /customers.json
Calling this endpoint will return an array of customer objects with a limit of 100 customer records at a time. Append an extra “page” parameter to this endpoint to paginate through your records:
https://api.cartfunnel.net/v1/customers.json?page=2
GET /customers/:id.json
This endpoint retrieves a single customer object. Replace the “:id” parameter with the ID of the customer record.
Example request:
https://api.cartfunnel.net/v1/customers/92310.json
The above call will retrieve the customer record with the ID of 92310, if the customer exists within the specified Cartfunnel account.
POST /customers.json
To create a new customer, you must supply at the very minimum an email address and creating a POST request to the above endpoint with
Example request:
https://api.cartfunnel.net/v1/customers.json
The request body:
{
"customer": {
"email": "[email protected]",
"first_name": "Anna",
"last_name": "Benning"
}
}
A successful response might look like this:
{
"id": 32199,
"email": "[email protected]",
"created_at": "2019-02-04T23:29:37.406-05:00",
"updated_at": "2019-02-04T23:29:37.406-05:00",
"accepts_marketing": "false",
"first_name": "Anna",
"last_name": "Benning",
"note": "",
"orders_count": 0,
"total_spent_cents": 0,
"tax_exempt": "false",
"subscriptions_count": 0,
"last_order_id": "null",
"persisted": "true"
}
You may notice that there are other attributes in the object, such as created_at and orders_count. Certain attributes are not modifiable and are automatically generated by Cartfunnel.
PATCH /customers/:id.json
To update a customer record, you can make a request to the above endpoint.
Example request:
https://api.cartfunnel.net/v1/customers.json
The request body:
{
"customer": {
"first_name": "Anna",
"last_name": "Jules"
}
}
Should the request be saved successfully, you will request a return JSON object without an errors attribute.
If an error occurs, you might see the following response:
{
"id": 32199,
"email": "[email protected]",
"created_at": "2019-02-04T23:29:37.406-05:00",
"updated_at": "2019-02-10T23:29:37.406-05:00",
"accepts_marketing": "false",
"first_name": "Anna",
"last_name": "Jules",
"note": "",
"orders_count": 0,
"total_spent_cents": 0,
"tax_exempt": "false",
"subscriptions_count": 0,
"last_order_id": "null",
"persisted": "true",
"errors": ["An error has occurred"]
}
You should check the return object to see if an “errors” attribute exists. If it exists, the record was not saved.
Customers — Addresses resource
The documentation for this resource is not yet available.
Customers — Subscriptions resource
The documentation for this resource is not yet available.
Products resource
The documentation for this resource is not yet available.
Orders resource
The documentation for this resource is not yet available.
Discounts resource
The Discounts resource enables you to:
- List all your discount codes (current, active, and disabled)
- View the details of a specific discount code
- Add new discount code
- Modify discount code
- Disable discount code
A discount object looks like this:
{ "id": 1, "applied_pretax": true, "applies_once": true, "applies_once_per_customer": true, "applies_to_id": 19882010, "applies_to_resource": "product", "apply_discount_to_resource_id": 19882010, "code": "mydiscountcode", "discount_type": "fixed_amount", "ends_at": "2019-06-10T23:29:37.406-05:00", "minimum_order_amount_cents": 0, "starts_at": "2019-06-01T23:29:37.406-05:00", "usage_limit": "null", "value": 1000 }
Properties
Attribute | Type | Notes |
applied_pretax | boolean | defaults to true |
applies_once | boolean | defaults to false |
applies_once_per_customer | boolean | defaults to false |
applies_to_id | integer | optional |
applies_to_resource | string | defaults to “store_wide”, options can be “store_wide” or “product” |
apply_discount_to_resource_id | integer | optional |
code | string | required |
discount_type | string | defaults to “fixed_amount”, can be “fixed_amount”, “percentage”, or “shipping” |
ends_at | datetime | required, UTC timestamp |
minimum_order_amount_cents | integer | defaults to 1000 (eg. $10.00), number should be cents value |
starts_at | datetime | required, UTC timestamp |
status | string | read only, either “enabled” or “disabled” |
times_used | integer | read only |
usage_limit | integer | optional, leave blank for unlimited |
value | integer | required, discount value in cents |
GET /discounts.json
Calling this endpoint will return an array of discount objects with a limit of 250 discount records at a time. Append an extra “page” parameter to this endpoint to paginate through your records:
https://api.cartfunnel.net/v1/discounts.json?page=2
GET /discounts/:id.json
Retrieve the record of a specific discount record as denoted by the ID.
Example request:
https://api.cartfunnel.net/v1/discounts/1601.json
The above request will retrieve the discount code with ID of 1601.
POST /discounts.json
Create a new discount code.
Example request:
https://api.cartfunnel.net/v1/discounts.json
The request body:
{ "discount": { "applied_pretax": true, "applies_once": true, "applies_once_per_customer": true, "code": "mydiscountcode", "discount_type": "fixed_amount", "ends_at": "2019-06-10T23:29:37.406-05:00", "minimum_order_amount_cents": 0, "starts_at": "2019-06-01T23:29:37.406-05:00", "usage_limit": "null", "value": 1000 } }
A successful response will return a full object such as illustrated above. Unsuccessful responses will return an error key.
PATCH /discounts/:id.json
You can call this endpoint to update an existing discount code. Note: In general, we do not recommend modifying a discount code once it has been released to your customers. It is better to create an entirely new discount code to ensure that settings are not changed midway through your marketing campaigns. For this reason, we recommend appending discount codes with the year or month it occurs to provide some level of uniqueness. Example: newyear2019 vs simply newyear.
Example request:
https://api.cartfunnel.net/v1/discounts/1601.json
The request body:
{ "discount": { "applied_pretax": false } }
DELETE /discounts/1601.json
Calling this endpoint will disable the discount. It will still be retrievable and can be re-enabled via the API.
Example request:
https://api.cartfunnel.net/v1/discounts/1601.json