PurchasePlus API
The PurchasePlus API is a RESTful API. It uses resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.
Overview
The PurchasePlus API is a RESTful API. It uses resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and a mix of standard and extended action verbs.

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

The API can be used by any Purchasing or Supplying Organisation in the PurchasePlus ecosystem. You will require the email address and password of a registered PurchasePlus user account to use the PurchasePlus API. To obtain a user account, please speak with an administrator at your Organisation, or contact our friendly customer success team.
API URLs
The PurchasePlus API can be accessed via the following URLs:

Production Environment: https://api.purchaseplus.com
Staging Environment: https://staging.api.purchaseplus.com
Technical Reference Documentation
Swaggerhub reference documentation is available for each of our separate API modules. We are in the process of thoroughly updating our documentation for each module, and we anticipate completion of this by July 2024. The app.swaggerhub.com paths shown below are being gradually replaced with the purchaseplus.com paths. In the meantime, please consider the app.swaggerhub.com paths insufficiently documented and maintained.

Access Module: https://purchaseplus.com/api-docs/index.html?urls.primaryName=Access%20API%20V2
Inventory Module: https://purchaseplus.com/api-docs/index.html?urls.primaryName=Inventory%20API%20V2
Point of Sale Module: https://purchaseplus.com/api-docs/index.html?urls.primaryName=Point%20Of%20Sale%20API%20V2
Purchasing Module: https://purchaseplus.com/api-docs/index.html?urls.primaryName=Purchasing%20API%20V2
Supplying Module: http://purchaseplus.com/api-docs/index.html?urls.primaryName=Supply%20API%20V2
Authentication
The PurchasePlus API uses token-based authentication. You will be required to make a request to sign in, upon which you will receive your Access-token, Client and Uid from the headers of a successful authentication.
To 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"
Change the email and password values to your own. If you receive an error at this point please refer to the errors section.

If you are successful you will receive a response containing information about your user account in the body of the response, and in the headers will be the Access-token, Client and Uid
Access-token XxhhFMpq-RQxBJb_LhuCNO
Client 4eWvqjwfS8KFaNG89dD4Tj
Uid your.name@yourorganisation.com
In all subsequent API calls you will need to provide those three header values in order to successfully call an endpoint.
$ 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 will have access to and what you can do with those resources 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 friendly customer success team.
Errors
PurchasePlus uses standard error codes to indicate whether your request was successful or there was an issue of some kind. The following table describes what the codes mean:
200 - OK
The request was successful.
400 - Bad Request
A bad request has been made, possibly missing data.
401 - Unauthorised
The authentication details you provided are incorrect. Follow the Authentication process carefully to ensure you are providing a valid Access-token, Client, and Uid.
403 - Forbidden
Your user account does not have the authorisation to perform that action or retrieve that data.
404 - Not Found
The resource you’ve asked for cannot be found. Check the URL carefully, and if an id was required, make sure it is correct.
406 - Not Acceptable
Your request is missing required attributes.
409 - Conflict
An indicator that the resource you are updating may have already been updated since you retrieved it.
429 - Too Many Requests
You have made too many API requests. Our current limit is 5 per second. If you feel this value is too low for your requirements please contact us.
500 - Error
This is an error on the PurchasePlus server and is out of your control. Please contact our team if the issue persists.
Pagination
For requests that return multiple records it may be necessary for you to make multiple requests to retrieve all the results. To do this you can 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
For a response that contains a resource it will contain a links attribute that will at minimum have a link to “self”, and if the resource has associated collections there will be links for those associations as well.
Pagination Links
For a response that returns a collection of resources a separate links object will be included.

This links object will contain links for:
first: The first page of the collection
last: The last page of the collection
next: The next page of the collection
prev: The previous page of the collection

For example;
"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 will contain a link to itself in the following format:
"links": {
  "self": "https://api.purchaseplus.com/supply/api/suppliers/xxx/catalogues/xxxxxx/priced_catalogued_products/xxxxxxx"
}
Each resource may also have links to relationships that are relevant that that resource. For instance, a sale may have a link for retrieving the lines for that sale. You can take this link and use it to make a subsequent API call to retrieve that information;
"relationships": {
  "lines": {
    "links": {
      "self": "https://api.purchaseplus.com/point_of_sale/api/sales/1/lines"
    }
  }
}
Each resource may also have relationship data that can be used to look up information from the included Related Resources, for example;
"relationships": {
  "product": {
    "data": {
      "type": "products",
      "id": "411853"
    }
  }
}
Related Resources
Some calls to retrieve resource data will also return related resources to save the need to make subsequent API calls.An example is retrieving product data on an invoice line, or details about a department 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 it is possible to filter the result of these using filter parameters.

An example which will return invoices containing 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"
The available options for the filters include:
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 Only compatible with string columns. Example: q[name_present]=1 (SQL: col is not null AND col != ”)
*_blank is null or empty (SQL: col is null OR col = ”)
*_null is null
*_not_null is not null
*_in match any values in array e.g. q[name_in][]=Alice&q[name_in][]=Bob
*_not_in match none of values in array
*_lt_any Less than any SQL: 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
*_matches_any *_does_not_match_any same as above but with LIKE
*_lt_all Less than all SQL: 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
*_matches_all Matches all same as above but with LIKE
*_does_not_match_all Does not match all
*_not_eq_all none of values in a set
*_start Starts with SQL: 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 SQL: 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
*_time_to
*_quarter_equals Matches any date that falls within the quarter. Can use either Q1, q1 or 1 (for quarter 1).
Request IDs
Each request you make to our API will be logged and assigned a request id. This Id is returned in the header as PP-Request-Id.
You can use this request id when making any requests for technical support for a particular request you are having issues with.
Versioning
The PurchasePlus API is currently on version 2.0. When making a request to the system you must provide the version information in the request header. If this is not provided, the system will assume you intend to use the deprecated version 1.0 API (API reference here: https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlus/1.0.0)

To set the version number on a request set the “Accept” header with a value of “application/vnd.mbapi.v2+json”
$ 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 being added, or any new or deleted fields.
Rate Limiting
The PurchasePlus API can optionally support idempotency which will help prevent the same transaction from occurring multiple times. In order to use this you must provide a header on your API request called “Idempotency-Key”. This is case sensitive and its value must be a UUID.

If you make a request with the same Idempotency-Key then you will receive a cached version of the original successful result. You should only be providing an Idempotency-Key for POST or PATCH requests as they are not needed for GET or DELETE.

Example:
$ 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"
Idempotent Requests
The PurchasePlus API has implemented rate limiting in order to protect all of our users from experiencing load issues. If your application reaches this rate limit you will begin to see HTTP error code 429 on your requests. Currently our limit is 5 requests per second per IP address. Please contact our team if the limit value is too low for your requirements.

In order to handle these errors gracefully we recommend that your application monitors for 429 errors and implements a retry mechanism whenever they occur.
Change Notes
September 2019
Version 2 of the PurchasePlus API is introduced (see Versioning section for more detail).
April 2024
An overhaul of the PurchasePlus Version 2 API commences. Updated swaggerhub documentation is underway for all modules. The team will review and update all of our Version 2 offering, and ensure that swaggerhub documentation reflects current functionality. We anticipate completion of this project by July of 2024, with the exciting addition of a new Supplying module.