CartRover API Documentation

The CartRover Orders API is a RESTful service that performs all data communication in JSON format. The order of the fields you submit is not important and the order of fields returned is not guaranteed.

There are three different levels of API access: cart, merchant, warehouse. Each provides access to different endpoints.

All API levels have separate access credentials but use the same authorization procedure and data formats for sending and receiving.

The CartRover API is still in development. All information and endpoints listed here are complete and may be used. New endpoints will be documented here as they become available.

To be notified of API changes, please join our API email group.

Table of Contents

Getting Help

If you have questions about the API, head over to CartRover Answers.

Check out the official CartRover PHP Client. Just include it directly in your project, we've done all the work for you!

Additional unofficial CartRover Libraries:

Authentication

Authentication can be done in one of two ways.

Basic Auth

Pass your API User and Key using the Basic Access Authentication standard.

  1. Concatenate the API user and key and place a colon in between: api_user:api_key
  2. Base 64 encode this string
  3. Pass it as a header in the following format: Authorization: Basic BASE64ENCODEDSTRING

URL Auth

Your credentials can be passed in the URL with each request. These credentials are secure in transit as the request is being made over SSL which encrypts the URL.

The GET Authentication parameters are:

  • api_user
  • api_key

Examples:

POST ORDERS: https://api.cartrover.com/v1/cart/orders/cartrover?api_user=SOMEUSER&api_key=SOMEKEY
GET ORDER XYZ: https://api.cartrover.com/v1/cart/orders/XYZ?api_user=SOMEUSER&api_key=SOMEKEY

Errors

All endpoints will return errors in the following format.

FieldData TypeDescription
success_codebooleanAlways FALSE for an error
error_codeENUM

Invalid - Invalid/Missing data submitted

Failure - Hard error like: Duplicate order

RateLimit - Over API Limit

status_messageStringSpecific Error Message


Rate Limit

The CartRover API uses a Leaky Bucket algorithm to manage API access. The bucket size is 100 calls, and they refill at rate of 1 call every 0.6 seconds. Currently the New Order API endpoint is NOT rate limited. If we see abuse of the API, all endpoints will be rate limited.

All endpoints that are rate limited will return the following header with each request. It contains the remaining number of API calls you can currently burst to:

X-CartRover-Api-Minute-Hits-Remaining

If you go over your rate limit, the API will return a standard error with the following code and message:

error_code: "RateLimit"

status_message: "Over API Limit. Please slow down requests."

Timestamps

Timestamp fields should be submitted to the API in ISO 8601 format in order to specify the timezone.

Timestamp fields returned by the API will be formatted in ISO 8601 and always be in the UTC timezone.

2016-08-27T02:24:58+00:00

If you are passing a timestamp as a GET parameter, YOU MUST encode the plus symbol (+) as %2B

Endpoints

The CartRover API has three levels. Each level has access to different functionality and has a separate set of credentials. Here we list each API level and which endpoints it has access to.

Note

Each endpoint will list its type (eg. GET, POST). Note that proper REST guidelines are not followed and most endpoints are GET. A future API version may change these endpoint types, but support for these API calls will remain for this version.


Cart API

Webhooks are also available.

Merchant API

Warehouse API

Webhooks

To learn about subscribing to Webhooks in the CartRover API, check out the Webhooks documentation page.

Sample Workflows

API Status

Is the CartRover API Down? Check our Status Page