API docs by Redocly

Partner API (1.0.3)

Download OpenAPI specification:Download

Partner API Introduction

Welcome to the Partner API by BuyBay, designed to streamline interactions between partners and BuyBay's return management system.

This API provides programmatic access to manage authentication, return item announcements, batches, deliveries, counted and graded returns, stock batches, orders, and stock license plates.

Environments and Endpoints

The Partner API is available in three environments: Test, Staging, and Production. Below are the base URLs for each environment:

Environment Base URL
Test https://partner-api.test.buybay.com
Staging https://partner-api.staging.buybay.com
Production https://partner-api.prod.buybay.com

All endpoints listed in this specification are relative to these base URLs. For example, the /api/v1/orders endpoint can be accessed as:

  • Test: https://partner-api.test.buybay.com/api/v1/orders
  • Staging: https://partner-api.staging.buybay.com/api/v1/orders
  • Production: https://partner-api.prod.buybay.com/api/v1/orders

Authentication

This API uses Bearer Token Authentication. Include this token in the Authorization header of subsequent requests as Bearer <token>.

Explore the endpoints below to learn more about each feature and how to integrate them into your workflows.

Deliveries

Gets the list of deliveries

Gets the list of deliveries belonging to the user's owner from the Partner Portal. They can be filtered by a delivery date interval.

Authorizations:
bearerAuth
query Parameters
start_date
string <date>

Filter deliveries from the start_date onwards

end_date
string <date>

Filter deliveries up until the end_date

scope
string
Enum: "all" "active" "cancelled"

Filter deliveries depending on the cancelled state. If scope is not provided, it will default to all and return all deliveries. If scope is active the result will be limited to non-cancelled deliveries. If scope is cancelled only cancelled deliveries are included.

reference
string <text>

Filter deliveries based on reference

page
integer
Example: page=1

The results' data page

per_page
integer
Default: 50
Example: per_page=20

The results' data page size

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Batches

Creates a batch of bulk returns

Creates a batch of items from Partner Portal which will result in bulk return announcements

Authorizations:
bearerAuth
Request Body schema: application/json
delivered_on
required
string <date>
delivery_time
required
string
Enum: "morning" "afternoon"
pallet_count
required
integer
publisher_reference
string or null
reference
required
string
Array of objects

Responses

Request samples

Content type
application/json
{
  • "delivered_on": "2022-01-01",
  • "delivery_time": "morning",
  • "pallet_count": 3,
  • "publisher_reference": "",
  • "reference": "PURCHASE-REF-1111",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Sales

Get license plate sales report.

Gets the list of sales belonging to the user. These can be filtered by a date range or by specific license plate code.

Authorizations:
bearerAuth
query Parameters
date_from
string <date>
Example: date_from=2025-11-01

Limit the sales report base on a start date

date_to
string <date>
Example: date_to=2025-11-30

Limit the sales report base on an end date

page
integer
Example: page=1

Limit the sales report to the desired page. Works alongside items param.

items
integer
Example: items=30

Determines how many license plates are returned per request. Defaults to 100.

code
string
Example: code=BW221201110425

Limit the sales report to a specific license plate

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Stocks

Get license plate stocks report

Gets the list of stocks belonging to the user. They can be filtered by specific license plate code.

Authorizations:
bearerAuth
query Parameters
page
integer
Example: page=1

Limit the stocks report to the desired page. Works alongside items param.

items
integer
Example: items=30

Determines how many license plates are returned per request. Defaults to 100.

code
string
Example: code=BW221201110425

Limit the stocks report to a specific license plate

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Returns

Partner returns

Allow partners to create returns (partner_direct_returns)

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "announcement": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Counted returns

Gets the list of counted returns for a specific date

Authorizations:
bearerAuth
query Parameters
date
required
string
Example: date=2022-12-01

The returns counting date

page
integer
Example: page=1

The results' data page

per_page
integer
Default: 50
Example: per_page=20

The results' data page size

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Graded returns

Gets the list of graded returns for a specific date

Authorizations:
bearerAuth
query Parameters
date
required
string
Example: date=2022-12-01

The returns grading date

page
integer
Example: page=1

The results' data page

per_page
integer
Default: 50
Example: per_page=20

The results' data page size

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Stock Batches

Get list of stock batches.

Authorizations:
bearerAuth
query Parameters
page
integer
Example: page=1

The results' data page

per_page
integer
Default: 50
Example: per_page=10

The results' data page size

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Creates a stock batch.

Authorizations:
bearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a specific stock batch by reference.

Authorizations:
bearerAuth
path Parameters
id
required
integer <int64>

Reference of the stock batch

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Orders

Get the list of orders.

Authorizations:
bearerAuth
query Parameters
status
string
Example: status=open

The type of order requested. Can either be open or processed

page
integer
Example: page=1

The results' data page

per_page
integer
Default: 50
Example: per_page=10

The results' data page size

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get a specific order by reference.

Authorizations:
bearerAuth
path Parameters
reference
required
string

Reference of the order.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Confirm a specific order by reference.

Authorizations:
bearerAuth
path Parameters
reference
required
string

Reference of the order.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Ship a specific order by reference.

Authorizations:
bearerAuth
path Parameters
reference
required
string

Reference of the order.

Request Body schema: application/json
carrier_code
string
tracking_code
string

Responses

Request samples

Content type
application/json
{
  • "carrier_code": "DPD",
  • "tracking_code": 5112063468209
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Stock license plate

Creates a stock item.

Authorizations:
bearerAuth
Request Body schema: application/json
license_plate
string

Responses

Request samples

Content type
application/json
{
  • "license_plate": "LOC-231215-99239-45"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}