PurchasePlus API

A RESTful API for the entire PurchasePlus platform.

Resource-oriented URLs, form-encoded request bodies, JSON-encoded responses, standard HTTP response codes, and a mix of standard and extended action verbs. Five separate modules cover purchasing, invoicing, inventory, point of sale, and supply.

Talk to Customer Success View API Reference

RESTful

Form-encoded requests

JSON responses

Token authentication

5 modules

cURL

# Sign in to obtain Access-token, Client and Uid
curl -D - "https://api.purchaseplus.com/access/api/auth/sign_in" \
  -H "Accept: application/vnd.mbapi.v2+json" \
  -d "email=you@yourbusiness.com&password=yourpassword"

# Subsequent request
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: you@yourorganisation.com"

Production

https://api.purchaseplus.com

Live production environment. Requires a registered PurchasePlus user account.

Staging

https://api.rc-purchaseplus.com

Sandbox environment for integration development and testing.

5 Modules

Five modules. One platform.

The API is broken into 5 separate modules representing functional areas within PurchasePlus. Each module has its own SwaggerHub reference documentation. Your application may need some or all, depending on your requirements.

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

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

Technical Reference

Everything you need to start building.

Authentication Token-based

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.

To Sign In

# 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'll need on every later call:

Access-tokenXxhhFMpq-RQxBJb_LhuCNO
Client4eWvqjwfS8KFaNG89dD4Tj
Uidyour.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 RBAC via Personas

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, please 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.

200OKRequest was successful
400Bad RequestPossibly missing data
401UnauthorisedInvalid Access-token, Client, or Uid
403ForbiddenPersona lacks permission
404Not FoundResource does not exist; check the URL or id
406Not AcceptableRequired attributes missing
409ConflictResource may have been updated since you retrieved it
429Too Many RequestsLimit is 5 per second
500Server ErrorContact support if it persists

Pagination page parameter

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 & 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" } } }

Filtering filter[field_predicate]=value

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 PP-Request-Id

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 v2.0

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 Idempotency-Key

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 5 rps / IP

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 2019Version 2 of the PurchasePlus API introducedv2.0
Apr 2024V2 API overhaul commences. SwaggerHub documentation underway across all modules, with a new Supplying moduleongoing

Get Connected

Connect with all of your suppliers digitally.

Let us help you connect with new and existing suppliers and boost your digital transformation.

Talk to Us

A RESTful API for the entire PurchasePlus platform.

Five modules. One platform.

Purchasing

Invoicing

Inventory

Point of Sale

Supply

Everything you need to start building.

Authentication Token-based

To Sign In

Subsequent Requests

Authorisation RBAC via Personas

Errors

Pagination page parameter

Links

Resource & Collection Links

Pagination Links

Relationship Links

Related Resources included[]

Filtering filter[field_predicate]=value

Request IDs PP-Request-Id

Versioning v2.0

Idempotent Requests Idempotency-Key

Rate Limiting 5 rps / IP

Change Notes

Connect with all of your suppliers digitally.