The Purchase Plus 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 separate modules representing functional areas within PurchasePlus. Each module has its own reference page. Your application may only need to interact with one or two of these modules depending on your requirements.
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 https://api.purchasplus.com/access/api/auth/sign_in -H “Accept: application/vnd.mbapi.v2+json” -d “email=your.name%40yourbusiness.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 firstname.lastname@example.org
In all subsequent API calls you will need to provide those three header values in order to successfully call an endpoint.
$ curl https://api.purchasplus.com/purchasing/api/purchaser/:id/invoices -H “Accept: application/vnd.mbapi.v2+json” -H “Access-token: “ -H “Client: “ -H “Uid: ”
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. Please contact email@example.com if you need access to additional resources.
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.|
|409 – Conflict||An indicator that the resource you are updating may have already been updated since you retrieved it.|
|500 – Error||This is an error on the PurchasePlus server out of your control. Please inform us if the issue persists.|
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.purchasplus.com/purchasing/api/purchaser/:id/invoices -H “Accept: application/vnd.mbapi.v2+json” -H “Access-token: ” -H “Client: ” -H “Uid: ” -d “page=2"
See the Links section for useful links that will provided to assist with retrieving paginated data.
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.
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 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.purchasplus.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:
|*_matches||matches with LIKE||e.g. q[email_matches]=%@gmail.com|
|*_does_not_match||does not match with LIKE|
|*_does_not_match_any||Does not match any|
|*_does_not_match_all||Does not match all|
|*_lteq||less than or equal|
|*_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 = ”)|
|*_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|
|*_fuzzy||Full text search|
|*_quarter_equals||Matches any date that falls within the quarter.||Can use either Q1, q1 or 1 (for quarter 1).|
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.
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 given then 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.purchasplus.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, and any new or deleted fields.
Version 2 of the PurchasePlus API is introduced (see Versioning section for more detail).
Initial endpoints in Version 2 will be for the Point of Sale module.
Using the API Reference
The API Reference is broken into a page for each module within PurchasePlus. Follow the link to the module you wish to review.
The documentation is hosted on SwaggerHub and has been specified using version 3.0.1 of the OpenAPI specification.
The endpoints for each PurchasePlus resource are grouped together at the top of the page. Expanding a resource will show you what actions are available.
At the bottom of the page is documentation regarding the schema of the resources themselves.
Using the “Try it out” function
If you do not have a user account yet with PurchasePlus you may use the virtual server for that module. It will return example responses based on the resource and action you have chosen.
If you wish to try out the endpoints using one of our real servers you may do so by choosing the appropriate server from the Servers drop down. Doing so will require you to have a user account on that system in order to retrieve your authentication details (See Authentication).
You will then need to click on the Authorize button to bring up a dialog to enter your Access-token, Client, and Uid.
“Try it out” caveats
If using the virtual server you will be receiving pre-determined example responses so do not expect the parameters you pass to the actions to match up with the example response. This does not apply when using the real server endpoints.
- Access – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Access/2.0
- Accounting – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Accounting/2.0
- Billing – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Billing/2.0
- Goods – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Goods/2.0
- Inventory – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Inventory/2.0
- Point of Sale – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-PointOfSale/2.0
- Purchasing – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Purchasing/2.0
- Rebates – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Rebates/2.0
- Recipes – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Recipes/2.0
- Supply – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Supply/2.0