Edit this doc

Conventions

Overview

With few exceptions, the OrderCloud API adheres to a RESTful architectural style. URIs, HTTP verbs, headers, payloads, and response codes all follow consistent and predictable patterns. This doc will outline conventions that permeate the entire platform.

SSL Everywhere

API access is only allowed via HTTPS; connections on port 80 are refused entirely. This simplifies the token-based authentication.

JSON Everywhere

UTF-8 encoded JSON is currently the only supported data format for both request and response payloads.

Date Format

Dates/times returned in the API are in UTC time and conform to ISO 8601.

OAuth 2

OrderCloud API authentication is based on the OAuth 2 specification and supports four different workflows, or, in OAuth terms, grant types. Check out our workflows guide to learn more.

Writeable IDs

Writable IDs can be extremely useful for back-office integrations. They can potentially eliminate the need for a mapping middleware layer.

Most resources that map to an entity of some sort (Orders, Users, Addresses, etc.) contain an ID that is optionally writable on creation or update. If you do not pass one, one will be auto-generated and returned in the response, and will be guaranteed to be unique. If you choose to pass an ID, you are responsible for ensuring uniqueness. Things that live under the context of a single Buyer need only be unique within that context. Things that are shared (such as products) must be unique across the entire Admin organization.

Error Handling

For all unsuccessful requests, we attempt to return the most appropriate HTTP status in the 400 range. Only when something goes terribly wrong on our end will you get a 500 response. And so long as our platform is responding (i.e. returing anything in the 4xx range or 500), you can count on the response body taking a standard shape.

HTTP Methods

A resource is a set of endpoints used to interact with an object of that same name. OrderCloud adheres to RESTful conventions in its usage of HTTP verbs. You can expect a subset of the following methods to exist on every Resource.

OrderCloud VerbHTTP VerbMeaningExample
GETGETReturns a specific itemGet a single address
SAVEPUTCreate or replace an item, you provide a unique IDCreate address ABC, overwriting it if it already exists
UPDATEPATCHUse it for updating itemsUpdate the name on an address by providing the new name
LISTGETReturns a list of itemsGet a list of addresses
CREATEPOSTCreates a new item, we generate a unique ID if no ID is providedCreate a new address
DELETEDELETEDeletes an itemDelete address ABC from the database

HTTP Status Code Summary

OrderCloud uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success and codes in the 4xx range indicate an error failed given the information provided (e.g., a required parameter). Only when something goes terribly wrong on our end will you receive a 500 response. As long as the platform is responding you can count on the response body taking a standard shape.

Status CodeSuggested Course of Action
200 - OKEverything worked as expected. No action required.
201 - CreatedSomething has been successfully created. No action required.
204 - No ContentThe server has successfully fulfilled the request. No action required.
401 - UnauthorizedThe user is not authorized to make a call to the API. Check that user credentials are valid and that there is a token on the headers in the format: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
403 - ForbiddenThe user's Security Profile does not have the necessary roles to make the API call. Update Security Profile to include valid roles for the call. The response will include a list of the missing roles
404 - Not FoundThe requested resource was not found. A common reason for this is a bad request.
500 - Internal Server ErrorThere was a server-side issue. Please contact us if you encounter this error code.