Support
API Reference

Introduction

🚧

The information presented in the Cratejoy API section applies to both the merchant and store API's

Cratejoy Store API

Cratejoy offers a Store API, which allows JavaScript to read (and sometimes write) data on behalf of logged-in customers. Theme developers and Merchants looking to customize their subscription workflow or customer account pages should see the Store API Introduction

Cratejoy Merchant API

The Cratejoy Merchant API provides an interface into most of the data and functionality of interest to merchants and developers. It is useful to merchants and developers looking to write custom scripts or back-end extensions.

There are some example scripts provided for reference purposes at https://github.com/cratejoy/api_examples

Resources

Resource representations are JSON throughout the API, by default. Agents should still send an Accept header with application/json for requests, and a Content-Type header with application/json for POST and PUT requests with a JSON body. In the future, the API may add support for other representations of data.

All data is encoded with UTF-8, and agents should send data encoded in UTF-8 to avoid problems. Queries and filters are URL parameters. All POST and PUT requests use a JSON body. No endpoints use Forms or URL parameters for updates.

URI Patterns

  • Major versions will be prefixed to all routes: /v1/{objects}/
  • Collection Resource URIs follow the pattern /{objects}/ (plural).
  • Element Resource URIs follow the pattern /{objects}/{id}.

Response Codes

2xx Successful Requests

  • 200 OK Will be returned for successful GET, PUT, and PATCH requests.
  • 201 Created Will be returned for successful POST requests.
  • 204 No Content Will be returned for successful DELETE requests

4xx Client Errors

  • 400 Bad Request for generic client errors.
  • 403 Forbidden when requesting a Resource which is not accessible by the client.
  • 404 Not Found when requesting a Resource which does not exist.
  • 405 Method Not Allowed when using an inappropriate HTTP method for a Resource.
  • 429 Too Many Requests when a client has issued too many requests.

5xx Server Errors

  • 500 Internal Server Error if we are having unspecified problems.
  • 503 Service Unavailable during expected downtime

Headers

  • Retry-After In the event of a 429 Too Many Requests, a Retry-After header will be included in the response. Agents can observe this value to retry at a later time. Time is returned in seconds until retry.