---
title: Conventions
slug: conventions
abstract: The OrderCloud API follows RESTful conventions including HTTPS, JSON, OAuth 2, and writeable IDs across all resources.
content_type: reference
audience: \[developer]
---

# Conventions

Learn about OrderCloud conventions and how the API's predictable nature enables interoperability.

The OrderCloud API adheres to a RESTful architectural style. URIs, HTTP verbs, headers, payloads, and response codes follow consistent and predictable patterns. This document outlines conventions that apply throughout the platform.

## HTTPS everywhere

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

## JSON everywhere

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

## Date format

Dates and times returned in the API are in UTC time and conform to [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601).

## OAuth 2

OrderCloud API authentication is based on the [OAuth 2 specification](http://tools.ietf.org/html/rfc6749) and supports four different workflows, or grant types. See our [workflows guide](https://doc.sitecore.com/ordercloud/en/developers/platform/authentication.html) to learn more.

## Writeable IDs

Writeable IDs are useful for back-office integrations as they can eliminate the need for a mapping middleware layer.

Most resources that map to an entity (Orders, Users, Addresses, etc.) contain an ID that is optionally writeable on creation or update. If you do not pass one, one is auto-generated and returned in the response, and is 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 Seller organization.

## Error handling

For all unsuccessful requests, we return the [most appropriate HTTP status in the 400 range](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error). As long as our platform is responding (returning anything in the 4xx range or 500), the response body follows a standard shape.

## 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 Verb| HTTP Verb| Meaning| Example
|---|---|---|---
GET| GET| Returns a specific item| Get a single address
SAVE| PUT| Create or replace an item, you provide a unique ID| Create address ABC, overwriting it if it already exists
PATCH| PATCH| Use it for updating items| Update the name on an address by providing the new name
LIST| GET| Returns a list of items| Get a list of addresses
CREATE| POST| Creates a new item, we generate a unique ID if no ID is provided| Create a new address
DELETE| DELETE| Deletes an item| Delete address ABC from the database

## Status code summary

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

Status Code| Suggested Course of Action
|---|---
200 - OK| Everything worked as expected. No action required.
201 - Created| Something has been successfully created. No action required.
204 - No Content| The server has successfully fulfilled the request. No action required.
401 - Unauthorized| The 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 - Forbidden| The 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.
400 - Bad Request| Something was wrong with the request. Use the response from the API to determine the corrective course of action.
404 - Not Found| The requested resource was not found. A common reason for this is a bad request.
409 - Conflict| The request conflicts with the current state of this or another resource.
500 - Internal Server Error| There was a server-side issue. Contact us if you encounter this error code.