# API Documentation | PurchasePlus

> Learn more about the PurchasePlus API.

Source: /api

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](/contact-us) [View API Reference](#ap-modules)

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](/api-docs/index.html?urls.primaryName=Purchasing%20API%20V2)[

### Invoicing

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

Open SwaggerHub Reference](/api-docs/index.html?urls.primaryName=Invoicing%20API%20V2)[

### Inventory

Stock levels, stocktakes, transfers, and variance tracking.

Open SwaggerHub Reference](/api-docs/index.html?urls.primaryName=Inventory%20API%20V2)[

### Point of Sale

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

Open SwaggerHub Reference](/api-docs/index.html?urls.primaryName=Point%20Of%20Sale%20API%20V3)[

### Supply

Supplier catalogues, product listings, pricing, and availability data.

Open SwaggerHub Reference](/api-docs/index.html?urls.primaryName=Supply%20API%20V2)

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.

#### On This Page

[Authentication](#ap-auth) [Authorisation](#ap-authz) [Errors](#ap-errors) [Pagination](#ap-pagination) [Links](#ap-links) [Related Resources](#ap-related) [Filtering](#ap-filters) [Request IDs](#ap-reqid) [Versioning](#ap-version) [Idempotent Requests](#ap-idem) [Rate Limiting](#ap-rate) [Change Notes](#ap-changes)

### 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-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 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](/contact-us).

### Errors

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

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

### Related Resources included\[\]

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 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 ([v1.0 reference here](https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlus/1.0.0)).

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 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`ongoing`

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](/talk-to-sales)