Collections

Collection Requests

All of Cratejoy's "collection" endpoints accept the following arguments:

• limit: Max number of results to return per query
• page: Page page number. So with limit=10 and page=3, you'll get items 31-40.

Collection pagination

Cratejoy's collection endpoints always return paginated results with data for multiple objects at a time. Collection endpoints always return data with the following attributes:

• count: The total number of results matched by the query
• next: The argument to attach to the url to retrieve the next page
• prev: The argument to attach to the url to retrieve the previous page
• results: An array of the current page's results

Element Responses

Related objects

Related objects will be returned with the "summary" attributes. This set of data is exactly the same as the summary in a Collection response. Some relationships are loaded by default, others can be requested using the with query parameter. See Working with Object Relationships for more details.

Elements will not be sent with an envelope.

Element Requests

Requests for Elements follow REST principles.

POST

• Will create an object with JSON data in the request body.
• Will return the complete representation of the created Element.
• Will return some 400 status on failure

PUT

• Will update a resource given an id with JSON data in the request body.
• Will return the complete representation of the Element on success.

🚧

Only pass properties that you want updated in a POST or PUT

Unknown or read-only properties passed in the POST or PUT will generate an error.

It may be tempting to GET an Item, update a property or two in the response, and then pass that entire response back in a PUT. Don't do that!

DELETE

• Will delete an Element given an id.
• Returns nothing on success.

Errors

When possible, the server will return a description of the error in a JSON body.

{
   "errors": [ 
       "Unknown property 'badprop'",
       "Invalid query parameter"
    ]
}

Field Conventions

Currency data

Currency is represented throughout as an integer, with the decimal portion inferred. E.g., "$4.50" is represented as 450.

Date and Times

Dates and times as an ISO 8601 combined data and time in UTC string 2015-09-12T23:06:19Z
All dates are UTC unless otherwise specified in the date string.

Status and other Enum values
Certain fields are stored in our database as integers and when filtering you have to use the enum value. For example, shipment status is returned or posted as as "unshipped", "shipped", or "cancelled", but when filtering a collection, you would filter on "statuseq=1", "statuseq=2", or "status__eq=3" respectively.