Standards

Where fields are optional and there is no value to be specified, these blank fields can either be null, or omitted.

All of our APIs use UTF8 encoded JSON, and we do not have complete support for all the available Unicode characters.

To ensure any characters you use in your API request (e.g. in the key value in the JSON body) will be accepted by the API you can stick to the Windows-1252 and/or the ISO/IEC 8859-1 standards.

We recommend that you use the following settings when calling Bunnings APIs.

All dates in API requests need to be in UTC date format unless told otherwise. Likewise, all API responses will be in UTC date format. Times are expressed in UTC, with a TZD timezone indicator to show the UTC timezone offset (e.g. Perth is UTC+08:00)

The format has the complete date plus hours, minutes and seconds:

YYYY-MM-DDThh:mm:ssTZD

(e.g. 2022-07-16T19:20:30+08:00)

All Bunnings APIs return RFC 7807 compliant error messages, and some also support extended Error Code functionality (those supporting Error Code functionality will have those Error Codes listed in their API Documentation).

When you receive an error from our APIs, a Problem Type URL (i.e. https://problem.api.bunnings.com.au?type=<problemName>) will be provided in the response where further details on the problem can be found.

For details on these Error Codes and the format of the errors see Error Codes.

Hypermedia as the engine of application state (HATEOAS), is the 4th constraint on REST in Roy Fielding’s dissertation. At the simplest level it states that each response message includes links for related records/objects, or the next request message (for example, a webpage provides hyperlinks to the browser to provide a way for the user to get to other webpages (or states)).

In reference to APIs, these are shown as links in the API response to get to the next resource, or related resources.

We provide HATEOAS conforming API responses where required and where it is practical. For example, the link to a specific record/object.

Some of our APIs provide a "_links" array, which will have links, operation ids and verbs to call from that responding API. Used in conjunction with the provided "_meta" array (in the sample below, referenced as {serverState}), a developer can hydrate the link and retrieve a particular record/object from that link.

{
 "id": 4,
 "modState": "ca1e0772-e568-4bf5-a018-03b3ceeb99c8",
 "criteria": {
  "lineSetType": [
   "BunningsDelivery",
   "DirectDelivery"
  ],
  "inventory": true,
  "shipmentClass": [
   "NextDayTimeSpecific"
  ]
 },
 "target": {
  "promiseMin": "00:00:00",
  "promiseMax": "12:00:00",
  "message": "Delivered by {DayStart} in the {AmPmStart}",
  "processingDays": "WorkingDays",
  "computePromiseFrom": "DeliveryTimeOfDay"
 },
 "_meta": {
  "_objectUuid": "4",
  "_objectVersion": "1",
  "serverState": "AUFkbWluLkZ1bGZpbG1lbnQuUHJvbWlzZS5WVmOWQyMzcDA1-ly_K83tgI"
 },
 "_links": [
  {
   "rel": "CHK:013/admin/promiseRules/audit/GET",
   "href": "/admin/promiseRules/audit/{serverState}",
   "methods": [
    "GET"
   ]
  }
 ]
}

HTTP response codes provide;

• A status code and title (or description)

• A type, with a URL link to more details

• Details on the error, if available

The following are the standard codes to expect when interfacing with Bunnings APIs.

Open Data Protocol (OData) is an open protocol that allows the creation and consumption of queryable and interoperable REST APIs in a simple and standard way.

At Bunnings, we have implemented part of the OData standard on many of our APIs. Specifically the queries standard (see OData Query Options for details).

At its simplest, this is a set of query parameters that allow you to query the data you have asked for. This will bring back a curated result according to the string you provide in your query parameter(s). For example, $select allows you to provide a "select statement" to filter the results to give you a subset of the objects from the API response (see OData $select query option for details).

NOTE: You will not be returned null objects when using OData parameters.

Common OData query parameters

The following is a list of common OData query parameters we use.

Some of our APIs require pagination to ensure rapid response times when dealing with a large set of items. When providing a paginated response we will provide these values in the response.

The paginated response will have links that can be used to retrieve other pages of data from the API.

Paginated Response Sample

{
  "pageSize": 20,
  "pageNumber": 1,
  "itemsCount": 2,
  "pageCount": 4,
  "items": [
    {
      "transactionRef": null,
      "transactionDate": "2020-11-09T04:52:07.3319174Z",
      "location": null,
      "terminalNumber": null,
      "totalAmount": 12,
      "itemQuantity": null,
      "customerType": null,
      "_meta": {
        "_objectUuid": "009e88fe-c600-457c-a803-6c827acedbfb",
        "_objectVersion": "1"
      },
      "_links": [
        {
          "rel": "TRA:003/GetTransactionDetails/GET",
          "href": "/transactions/{transactionRef}",
          "methods": [
            "GET"
          ]
        },
        {
          "rel": "TRA:005/GetPdfTransactionReceipt/GET",
          "href": "/receipts/{transactionRef}?type=PDF&cid={correlationId}",
          "methods": [
            "GET"
          ]
        },
        {
          "rel": "TRA:006/GetPngTransactionReceipt/GET",
          "href": "/receipts/{transactionRef}?type=PNG&cid={correlationId}",
          "methods": [
            "GET"
          ]
        }
      ]
    },
    {
      "transactionRef": null,
      "transactionDate": "2020-11-09T04:52:07.3319256Z",
      "location": null,
      "terminalNumber": null,
      "totalAmount": 24,
      "itemQuantity": null,
      "customerType": null,
      "_meta": {
        "_objectUuid": "7b8db708-a5dd-4d61-9c08-de69590b3c22",
        "_objectVersion": "1"
      },
      "_links": [
        {
          "rel": "TRA:003/GetTransactionDetails/GET",
          "href": "/transactions/{transactionRef}",
          "methods": [
            "GET"
          ]
        },
        {
          "rel": "TRA:005/GetPdfTransactionReceipt/GET",
          "href": "/receipts/{transactionRef}?type=PDF&cid={correlationId}",
          "methods": [
            "GET"
          ]
        },
        {
          "rel": "TRA:006/GetPngTransactionReceipt/GET",
          "href": "/receipts/{transactionRef}?type=PNG&cid={correlationId}",
          "methods": [
            "GET"
          ]
        }
      ]
    }
  ],
  "_meta": {
    "_objectUuid": "c387aaae-36eb-4801-8c0e-55a8a24d398e",
    "_objectVersion": "1"
  },
  "_links": []
}

Using Pagination

When you receive a response with pagination, you will need to provide particular parameters to retrieve the other records (pages) as part of your request.

cURL pagination request example

curl --request POST \
  'https://transaction.sandbox.api.bunnings.com.au/transaction/transactions/search?continuationToken=c387aaae-36eb-4801-8c0e-55a8a24d398e&page=2&pageSize=20&%24fullPage=true' \
  --header 'x-version-api: 1.1' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

The following are standard headers we generally require in the API call, unless indicated otherwise. See the particular API products OpenAPI Specification (API Reference) for confirmation on header requirements.

The following are standard response headers we generally provide on our API responses, unless otherwise indicated. See the particular API products OpenAPI Specification (API Reference) for confirmation on what response headers to expect.

To protect the backend service from overload, Bunnings enforces traffic limits in the form of Quotas and Spike Arrests. For details about the traffic limits see Quotas and Spike Arrest pages.

We have particular URLs for each of our environments, and each of our APIs, so that you and Bunnings can clearly distinguish which API environment and API product you are interfacing with;

The exception to above is our OAuth2 service, see OAuth2 Token Endpoint for details. Where the {service} prefix denotes the API service, which may differ for each API product.

Verbs

We use all verbs (or methods) that are available as part of HTTP. See Section 9 in RFC 2616 for further details.

Hypermedia

The content we provide in our API responses will almost always be application/json or application/xml. We may provide some responses in other formats (e.g. application/pdf) depending on requirement of the API.

The latest version of our API is shown in the API Reference (Open API Specification) for each API product. This will be at the beginning of the specification in the version: field. For example; version: v1.1

Using the API version

For every API request you must add the x-version-api header parameter and include the version number (without the “v”) in the API Request.

cURL example

curl --request POST \
  'https://payment.sandbox.api.bunnings.com.au/payment' \
  --header 'x-version-api: 1.1'

Deprecation and version management

We will notify developers of any impending version changes and deprecations.

Bunnings will maintain at most the current version and 1 deprecated version (if available). Any deprecated version will be available for 1 year. Any use of a deprecated API version will provide end-of-life (EOL) headers that will describe the state of that deprecated API version.