Introduction

ATUM 1.8.8+ is fully integrated with the WooCommerce and WordPress REST APIs. This allows ATUM data to be created, read, updated, and deleted using requests in JSON format and using WordPress REST API Authentication methods and standard HTTP verbs which are understood by most HTTP clients.

The current WP REST API integration version is v3 which takes a first-order position in endpoints.

The following table shows API versions present in each major version of WooCommerce:

These API Docs are restricted to ATUM data, if you want to read docs for the other WC endpoints, we suggest you read the WC REST API Docs.

Some of the endpoints described on these docs are just the ones described in the WC's official API docs but with extra info regarding ATUM data. The data added by ATUM to the official WC's endpoints can be identified in these docs with the label: ATUM.

There is info described here that it's ony available when some of the ATUM's premium add-ons are active. We'll identify them with orange labels like Multi-Inventory or Product Levels.

RequirementsCopy Anchor Link

To use the latest version of the REST API you must be using:

• ATUM Inventory Management for WooCommerce 1.8.8+.
• WooCommerce 3.6+.
• WordPress 5.0+.
• Pretty permalinks in Settings > Permalinks so that the custom endpoints are supported. Default permalinks will not work.
• You may access the API over either HTTP or HTTPS, but HTTPS is recommended where possible.

If you use ModSecurity and see 501 Method Not Implemented errors, see this issue for details.

Request/Response FormatCopy Anchor Link

The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a 200 OK HTTP status.

Some general information about responses:

• Dates are returned in ISO8601 format: YYYY-MM-DDTHH:MM:SS
• Resource IDs are returned as integers.
• Other amounts, such as item counts, are returned as integers.
• Blank fields are generally included as null or emtpy string instead of being omitted.

JSONP SupportCopy Anchor Link

The WP REST API supports JSONP by default. JSONP responses use the application/javascript content-type. You can specify the callback using the ?_jsonp parameter for GET requests to have the response wrapped in a JSON function:

curl https://example.com/wp-json/wc/v3/products/tags/34?_jsonp=tagDetails \
	-u consumer_key:consumer_secret

/**/tagDetails({"id":34,"name":"Leather Shoes","slug":"leather-shoes","description":"","count":0,"_links":{"self":[{"href":"https://example.com/wp-json/wc/v3/products/tags/34"}],"collection":[{"href":"https://example.com/wp-json/wc/v3/products/tags"}]}})%

ErrorsCopy Anchor Link

Occasionally you might encounter errors when accessing the REST API. There are four possible types:

{
  "code": "rest_no_route",
  "message": "No route was found matching the URL and request method",
  "data": {
    "status": 404
  }
}

{
  "code": "woocommerce_rest_term_invalid",
  "message": "Resource doesn't exist.",
  "data": {
    "status": 404
  }
}

{
  "code": "atum_rest_term_invalid",
  "message": "Resource doesn't exist.",
  "data": {
    "status": 404
  }
}

Errors return both an appropriate HTTP status code and response object which contains a code, message and data attribute.

ParametersCopy Anchor Link

Almost all endpoints accept optional parameters which can be passed as a HTTP query string parameter, e.g. GET /orders?status=completed. All parameters are documented along each endpoint.

PaginationCopy Anchor Link

Requests that return multiple items will be paginated to 10 items by default. This default can be changed by the site administrator by changing the posts_per_page option. Alternatively the items per page can be specified with the ?per_page parameter:

GET /atum/purchase-orders?per_page=15

You can specify further pages with the ?page parameter:

GET /atum/purchase-orders?page=2

You may also specify the offset from the first resource using the ?offset parameter:

GET /atum/purchase-orders?offset=5

Page number is 1-based and omitting the ?page parameter will return the first page.

The total number of resources and pages are always included in the X-WP-Total and X-WP-TotalPages HTTP headers.

Link HeaderCopy Anchor Link

Pagination info is included in the Link Header. It's recommended that you follow these values instead of building your own URLs where possible.

Link: <https://www.example.com/wp-json/wc/v3/products?page=2>; rel="next",
<https://www.example.com/wp-json/wc/v3/products?page=3>; rel="last"`

The possible rel values are:

Libraries and ToolsCopy Anchor Link

Official WooCommerce librariesCopy Anchor Link

• JavaScript Library
• PHP Library
• Python Library
• Ruby Library

// Install:
// npm install --save @woocommerce/woocommerce-rest-api

// Setup:
const WooCommerceRestApi = require("@woocommerce/woocommerce-rest-api").default;
// import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api"; // Supports ESM

const WooCommerce = new WooCommerceRestApi({
  url: 'http://example.com', // Your store URL
  consumerKey: 'consumer_key', // Your consumer key
  consumerSecret: 'consumer_secret', // Your consumer secret
  version: 'wc/v3' // WooCommerce WP REST API version
});

Third party librariesCopy Anchor Link

• Java Library
• .NET Library
• Android Library

API ToolsCopy Anchor Link

Some useful tools you can use to access the API include:

• Postman - Cross-platform REST client, available for Mac, Windows, and Linux.
• Insomnia - Cross-platform GraphQL and REST client, available for Mac, Windows, and Linux.
• RequestBin - Allows you test webhooks.
• Hookbin - Another tool to test webhooks.

Learn moreCopy Anchor Link

Learn more about the REST API checking the official WordPress REST API documentation.