• Products
  • Offerings
  • PricingPlans
  • Invoices
  • InvoiceGroups
  • Orders
  • Quotes
  • Entitlements
Platform
Commerce / Reference / REST API

About

Postman Collection
OpenAPI

This is the reference for the Commerce Cloud Platform REST API. This API is the primary way to get and modify data in Commerce, whether you are developing an app or any other integration. Use it to interact with Commerce entities, like orders, quotes, offerings, and pricing plans.

Authentication

The Commerce API requires a token for authentication. Make sure to include your generated access token as an authorization header in all requests.

1
2
curl --request GET \
--url "https://api.atlassian.com/commerce/api..." \
--header "Authorization: Bearer ACCESS_TOKEN"

Pagination

The Commerce API uses cursor-based pagination to limit response size for resources that may return large numbers of results. HTTP clients may specify a smaller page size of N by adding the query parameter page-size=N. The supported query parameters for pagination are:

  • start-id (optional) - Specifies the starting cursor to skip entries.
  • page-size (optional) - Specifies the maximum page size, the default value can vary by resource.

The response for paginated endpoints will contain the following fragment:

1
2
{
  "values" :[
    // resource object
  ],
  "nextId": <String>
}

The nextId attribute in the response payload should be used as the start-id query parameter to load entries from the next page of results.

Dates

All dates returned by the API are Unix timestamps.

Monetary amounts

On Product and Quote APIs the currency values are accepted, and returned, in the lowest denominator. For example, for USD all values are returned in cents, for $1.00 the returned value is 100. For the rest of Commerce APIs the returned values are in dollar amount. Commerce will be looking at standardizing this in the future.

Errors

The following response status codes may be accompanied by an error representation.

StatusDescription
400Request body is malformed or has an illegal property value.
401Authentication is required.
403User was authenticated but is not authorized for this operation.
404Resource does not exist or is not visible to this user.
422The request body contains semantic errors.
429The client has exceeded the rate limit.
500Unexpected internal error in Commerce.
502Unexpected error in an external service.

Error responses will contain a JSON representation like in the example below:

1
2
{
  "title": "Invalid parameter: trial",
  "code": "parameter_invalid",
  "detail": "Invalid value :123123",
  "id": "uuid",
  "status": "400"
}

Rate this page: