API reference

Environments

Use the production host for live data. Use staging while you build and test an integration. Both require a registered PurchasePlus user account.

Environment	Base URL	Use
Production	`https://api.purchaseplus.com`	Live production environment.
Staging	`https://api.rc-purchaseplus.com`	Sandbox for integration development and testing.

Modules

The API is broken into separate modules for functional areas in PurchasePlus. Each module has its own SwaggerHub reference. Your application may need some or all of them.

Purchasing

Purchase orders, approvals, receiving notes, and supplier interactions. Open SwaggerHub reference.

Invoicing

Invoices, AP automation, 3-way matching, approvals, and accounting exports. Open SwaggerHub reference.

Inventory

Stock levels, stocktakes, transfers, and variance tracking. Open SwaggerHub reference.

Point of Sale

Point of sale transactions, sales records, and till integration data. Open SwaggerHub reference.

Supply

Supplier catalogues, product listings, pricing, and availability data. Open SwaggerHub reference.

Recipes

Recipes, menu items, ingredients, and costings. Open SwaggerHub reference.

SwaggerHub paths above are gradually replacing legacy app.swaggerhub.com references. Treat any remaining app.swaggerhub.com docs as insufficiently maintained.

Authentication

The PurchasePlus API uses token-based authentication. Make a sign-in request with your account email and password. The response headers contain Access-token, Client, and Uid, which must be passed on every subsequent request.

# Sign in
curl -D - "https://api.purchaseplus.com/access/api/auth/sign_in" \
  -H "Accept: application/vnd.mbapi.v2+json" \
  -d "email=your.name@yourbusiness.com&password=yourpassword"

If the request is successful, the response body contains your user account details. The headers contain the three values you need on every later call:

Access-token — XxhhFMpq-RQxBJb_LhuCNO
Client — 4eWvqjwfS8KFaNG89dD4Tj
Uid — your.name@yourorganisation.com

Subsequent Requests

curl "https://api.purchaseplus.com/purchasing/api/purchaser/:id/invoices" \
  -H "Accept: application/vnd.mbapi.v2+json" \
  -H "Access-token: XxhhFMpq-RQxBJb_LhuCNO" \
  -H "Client: 4eWvqjwfS8KFaNG89dD4Tj" \
  -H "Uid: your.name@yourorganisation.com"

Authorisation

Once your user is authenticated, the resources you can access and what you can do with them is controlled by the authorisation system. This is currently based on the Personas your user has been assigned, and can only be maintained through the PurchasePlus user interface. To obtain additional authorisation, speak with an administrator at your organisation, or contact our customer success team.

Errors

The PurchasePlus API uses standard HTTP response codes to indicate whether your request was successful or whether there was an issue.

Code	Status	Meaning
`200`	OK	Request was successful
`400`	Bad Request	Possibly missing data
`401`	Unauthorised	Invalid Access-token, Client, or Uid
`403`	Forbidden	Persona lacks permission
`404`	Not Found	Resource does not exist; check the URL or id
`406`	Not Acceptable	Required attributes missing
`409`	Conflict	Resource may have been updated since you retrieved it
`429`	Too Many Requests	Limit is 5 per second
`500`	Server Error	Contact support if it persists

Pagination

For requests that return multiple records, you may need to make multiple requests to retrieve all results. Pass the page parameter with the page number you wish to request.

curl "https://api.purchaseplus.com/purchasing/api/purchaser/:id/invoices" \
  -H "Accept: application/vnd.mbapi.v2+json" \
  -H "Access-token: ..." \
  -H "Client: ..." \
  -H "Uid: ..." \
  -d "page=2"

Links

Resource and Collection Links

Every resource response contains a links attribute with a link to self, plus links to any associated collections.

Pagination Links

Responses returning a collection include a links object with first, last, next, and prev page links.

"links": {
  "first": "https://api.purchaseplus.com/supply/en/api/suppliers/xxx/catalogues?page=1&per_page=25",
  "last":  "https://api.purchaseplus.com/supply/en/api/suppliers/xxx/catalogues?page=2&per_page=25",
  "prev":  null,
  "next":  "https://api.purchaseplus.com/supply/en/api/suppliers/xxx/catalogues?page=2&per_page=25"
}

Relationship Links

Every resource contains a self-link, and may also expose related resources you can fetch with subsequent calls.

"links": {
  "self": "https://api.purchaseplus.com/supply/api/suppliers/xxx/catalogues/xxxxxx/priced_catalogued_products/xxxxxxx"
}

"relationships": {
  "lines": {
    "links": {
      "self": "https://api.purchaseplus.com/point_of_sale/api/sales/1/lines"
    }
  }
}

"relationships": {
  "product": {
    "data": { "type": "products", "id": "411853" }
  }
}

Some calls return related resources alongside the primary data, saving the need for subsequent API calls. For example, retrieving a product's details from an invoice line, or department details with an invoice.

"included": [
  {
    "id":   "xxxxxx",
    "type": "products",
    "attributes": {
      "concatenated_description": "Chicken Thigh Meat : Diced (AW 2.5kg) 1 kg"
    }
  }
]

Filtering

For requests that return multiple records, you can filter results using filter parameters. Example, returning invoices with the string "INV":

curl "https://api.purchaseplus.com/purchasing/api/purchaser/:id/invoices" \
  -H "Accept: application/vnd.mbapi.v2+json" \
  -H "Access-token: ..." \
  -H "Client: ..." \
  -H "Uid: ..." \
  -d "filter[invoice_number_cont]=INV"

Available predicates:

Predicate	Description	Notes
`*_eq`	equal
`*_not_eq`	not equal
`*_matches`	matches with LIKE	e.g. q[email_matches]=%@gmail.com
`*_does_not_match`	does not match with LIKE
`*_matches_any`	matches any
`*_matches_all`	matches all
`*_does_not_match_any`	does not match any
`*_does_not_match_all`	does not match all
`*_lt`	less than
`*_lteq`	less than or equal
`*_gt`	greater than
`*_gteq`	greater than or equal
`*_present`	not null and not empty	String columns only. q[name_present]=1
`*_blank`	is null or empty	col IS NULL OR col = ''
`*_null`	is null
`*_not_null`	is not null
`*_in`	match any values in array	q[name_in][]=Alice&q[name_in][]=Bob
`*_not_in`	match none of values in array
`*_lt_any`	less than any	col < value1 OR col < value2
`*_lteq_any`	less than or equal to any
`*_gt_any`	greater than any
`*_gteq_any`	greater than or equal to any
`*_lt_all`	less than all	col < value1 AND col < value2
`*_lteq_all`	less than or equal to all
`*_gt_all`	greater than all
`*_gteq_all`	greater than or equal to all
`*_not_eq_all`	none of values in a set
`*_start`	starts with	col LIKE 'value%'
`*_not_start`	does not start with
`*_start_any`	starts with any of
`*_start_all`	starts with all of
`*_not_start_any`	does not start with any of
`*_not_start_all`	does not start with all of
`*_end`	ends with	col LIKE '%value'
`*_not_end`	does not end with
`*_end_any`	ends with any of
`*_end_all`	ends with all of
`*_cont`	contains value	uses LIKE
`*_cont_any`	contains any of
`*_cont_all`	contains all of
`*_not_cont`	does not contain
`*_not_cont_any`	does not contain any of
`*_not_cont_all`	does not contain all of
`*_true`	is true
`*_false`	is false
`*_fuzzy`	full text search
`*_time_from`	after this time
`*_time_to`	before this time
`*_quarter_equals`	matches a date in the quarter	Q1, q1 or 1

Request IDs

Each request you make to our API is logged and assigned a request id, returned in the PP-Request-Id response header. Use this id when contacting support about a specific request.

Versioning

The PurchasePlus API is currently on version 2.0. Provide the version on every request via the Accept header. If omitted, the system falls back to the deprecated v1.0 API.

curl "https://api.purchaseplus.com/access/api/auth/sign_in" \
  -H "Accept: application/vnd.mbapi.v2+json"

Refer to the Change Notes below for any breaking version changes, new endpoints, or new and deleted fields.

Idempotent Requests

The PurchasePlus API can optionally support idempotency to prevent the same transaction occurring multiple times. Provide the case-sensitive Idempotency-Key header on a request, with a UUID as its value.

If you make a request with the same Idempotency-Key twice, you receive the cached version of the original successful result. Only provide an Idempotency-Key for POST or PATCH requests, never GET or DELETE.

curl "https://api.purchaseplus.com/purchasing/api/purchaser/:id/invoices" \
  -H "Accept: application/vnd.mbapi.v2+json" \
  -H "Idempotency-Key: ca2a1871-82a2-496f-a2d2-3525d69426c3" \
  -H "Access-token: XxhhFMpq-RQxBJb_LhuCNO" \
  -H "Client: 4eWvqjwfS8KFaNG89dD4Tj" \
  -H "Uid: your.name@yourorganisation.com"

Rate Limiting

The PurchasePlus API is rate limited to protect all users from load issues. If your application reaches the limit you will see HTTP 429 on requests. The current limit is 5 requests per second per IP address. Contact our team if this is too low for your requirements.

Handle these errors gracefully by monitoring for 429s and implementing a retry mechanism with back-off.

Change Notes

Sep 2019 — Version 2 of the PurchasePlus API introduced (v2.0).
Apr 2024 — V2 API overhaul commences. SwaggerHub documentation underway across all modules, with a new Supplying module.