Cartfunnel REST API

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
email	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