BigblueDevelopers

Returns

Returns bring units from a customer back to a warehouse.

A return records the units a customer sends back, what the warehouse received, their condition and how the customer was refunded. Every return belongs to an order.

Operations

Create return

Create a return for an order.

Update return

Close a return and record the refund.

Get return

See what the warehouse received.

List returns

List returns for an order or a period.

Two statuses

A return has two separate status fields:

status
Where the parcel is
Created, shipped or received at the warehouse.
resolution_status
Whether the refund is settled
Open, action required or closed.

For example, a return can be RETURN_STATUS_RETURNED while its resolution_status is ACTION_REQUIRED because the customer hasn't been refunded.

status

RETURN_STATUS_CREATED
Created. Nothing has shipped yet.
RETURN_STATUS_TRANSMITTED
Sent to the warehouse and carrier. A label may exist.
RETURN_STATUS_SHIPPED
The customer sent the parcel.
RETURN_STATUS_RETURNED
Received by the warehouse. Units are back in inventory.
RETURN_STATUS_EXCEPTION
A problem needs attention.
RETURN_STATUS_CANCELLED
Cancelled.
RETURN_STATUS_UNSPECIFIED
Unknown status.

resolution_status

RETURN_RESOLUTION_STATUS_OPEN
Open. Usual status until the parcel arrives.
RETURN_RESOLUTION_STATUS_ACTION_REQUIRED
You need to act, usually to refund the customer.
RETURN_RESOLUTION_STATUS_CLOSED
Settled.
RETURN_RESOLUTION_STATUS_UNSPECIFIED
Unknown status.

Use UpdateReturn to close a return and record how you refunded the customer.

The Return object

idstring

Return ID: the order ID, RT, then two characters. Example: BGBL0K3M9XQ2RT01.

Pattern^[A-Za-z0-9]{12}RT[A-Za-z0-9]{2}$
orderstring
The order the units came from.
Pattern^[A-Za-z0-9]{12}$
external_idstring
Your own reference.
Up to 64 characters
storestring
The sales channel.
Up to 11 characters
warehousestring
The warehouse receiving the return.
Pattern^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$
fulfillmentstring
The fulfillment the units originally shipped in.
line_itemsReturnLineItem[]
Units being returned. At least one line.
statusReturnStatus
Parcel status.
resolution_statusReturnResolutionStatus
Refund status.
create_timestring
When the return was created.
update_timestring
When it last changed.
return_timestring
When the warehouse received it.
resolution_closed_timestring
When the resolution was closed.
RFC 3339 in UTC, for example 2026-03-14T09:30:00Z
label_urlstring
Return label for the customer, if Bigblue created one.
tracking_numberstring
Tracking number of the return parcel.
carrier_servicestring
Carrier service of the return parcel.
label_generation_supportReturn.LabelGenerationSupport

SUPPORTED or UNSUPPORTED: whether Bigblue can create a return label for this route.

sourceReturnSource
Who created the return.
originReturnOrigin
Where the return comes from.
utm_mediumstring

How the customer reached the returns page, for example email or qr_code.

refund_methodReturnRefundMethod

How the customer chose to be refunded.

currencystring
Currency of the amounts on the return.
Exactly 3 characters
refund_feestring
Amount taken off the refund, usually the label fee.
gift_cardReturnGiftCard

Store credit issued, for store credit refunds.

exchangeReturnExchange
Replacement items, for exchanges.
manual_resolutionReturnManualResolution

Set when you close the return yourself.

ReturnLineItem

productstringrequired
Product ID. Bundles can't be returned as a whole.
Pattern^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$
expected_quantityintegerrequired
Units the customer is sending. Greater than 0.
Greater than 0
received_quantityinteger
Units the warehouse received, including damaged units.
damaged_quantityinteger
Received units that are damaged.
idstring
Your own line ID. Must be unique in the return.
Up to 64 characters
return_reasonsReturnReason[]

One reason per unit when the customer gave them. There may be fewer if you or the warehouse created the return.

quality_controlsReturnQualityControl[]

One inspection result per unit, from the warehouse.

Units that can be sold again are received_quantity - damaged_quantity. Damaged units go to damaged in inventory.

ReturnReason

typeReturnReasonType
Main reason.
commentstring
The customer's comment.
Up to 500 characters

ReturnReasonType

RETURN_REASON_TYPE_ITEM_TOO_BIG
Too big.
RETURN_REASON_TYPE_ITEM_TOO_SMALL
Too small.
RETURN_REASON_TYPE_WRONG_DESCRIPTION
Different from the description.
RETURN_REASON_TYPE_ITEM_DISLIKED
The customer doesn't like it.
RETURN_REASON_TYPE_DAMAGED_ITEM
Damaged or faulty.
RETURN_REASON_TYPE_WRONG_ITEM_RECEIVED
Not the item ordered.
RETURN_REASON_TYPE_OTHER
Other reason. See the comment.
RETURN_REASON_TYPE_UNSPECIFIED
No reason given.

ReturnQualityControl

damaged_reasonsReturnDamagedReason[]
What's wrong with the unit.
imagesReturnQualityControlImage[]
Inspection photos. Each is { "url": "https://..." }.
serial_numberReturnQualityControl.SerialNumber

Serial number of the unit, if recorded: { "type": "RETURN_SERIAL_NUMBER_TYPE_IMEI", "value": "..." }.

ReturnDamagedReason

RETURN_DAMAGED_REASON_CRUMPLED_PRODUCT
The product is crumpled.
RETURN_DAMAGED_REASON_DAMAGED_PACKAGING
The packaging is damaged.
RETURN_DAMAGED_REASON_DAMAGED_PRODUCT
The product is damaged.
RETURN_DAMAGED_REASON_MISSING_OR_UNREADABLE_BARCODE
The barcode is missing or can't be read.
RETURN_DAMAGED_REASON_DIRTY_PRODUCT
The product is dirty.
RETURN_DAMAGED_REASON_SERIAL_NUMBER_MISMATCH
The serial number is missing or wrong.
RETURN_DAMAGED_REASON_UNSPECIFIED
No reason recorded.

ReturnSource

RETURN_SOURCE_CUSTOMER
Created by the customer on the returns page.
RETURN_SOURCE_MERCHANT
Created by you, in the app or the API.
RETURN_SOURCE_WAREHOUSE
The warehouse received a parcel with no return record.
RETURN_SOURCE_INTEGRATION
Created by a third-party returns app.
RETURN_SOURCE_CARRIER
The original parcel came back undelivered.
RETURN_SOURCE_UNSPECIFIED
Unknown.

ReturnRefundMethod

RETURN_REFUND_METHOD_UNSPECIFIED
Manual refund. You refund the customer yourself. This is the default.
RETURN_REFUND_METHOD_STORE_CREDIT
The customer gets store credit. See gift_card.
RETURN_REFUND_METHOD_EXCHANGE
The customer gets replacement items. See exchange.
RETURN_REFUND_METHOD_MANUAL_OTHER
You closed the return and chose "other" as the refund method.

ReturnOrigin

postalstring
Postal code.
Up to 12 characters
statestring
State or province.
Up to 38 characters
countrystring
ISO 3166-1 alpha-2.
Exactly 2 characters

ReturnGiftCard

store_gift_card_idstring
Gift card ID in your shop.
initial_valuestring
Credit amount.
notestring
Description of the gift card.
code_last_charactersstring
Last four characters of the code.
Pattern^[A-Za-z0-9]{4}$
create_timestring
When the gift card was created.
RFC 3339 in UTC, for example 2026-03-14T09:30:00Z

ReturnExchange

line_itemsReturnExchangeLineItem[]
Replacement items. At least one.
shipping_pricestring

Shipping for the replacement items. Empty until the customer completes checkout.

to_refund_amountstring

Amount still owed to the customer: returned items minus replacement items, shipping and refund_fee. Empty until checkout is complete.

ReturnExchangeLineItem

productstring

Bigblue product or bundle. Empty if the shop product isn't linked to Bigblue.

Pattern^[A-Za-z0-9]{4}(BU)?-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$
product_idstring
Product ID in your shop.
variant_idstring
Variant ID in your shop, if any.
product_titlestring
Product title.
quantityinteger
Units. Greater than 0.
pricestring
Line price after discounts. Empty until checkout is complete.

ReturnManualResolution

refund_methodReturnRefundMethod
How you refunded the customer.
notestring
A note about the resolution.

List trackings

Find trackings by order ID, your order reference or tracking number.

Create return

Create a return so the warehouse expects the units.

On this page

OperationsTwo statusesstatusresolution_statusThe Return objectReturnLineItemReturnReasonReturnReasonTypeReturnQualityControlReturnDamagedReasonReturnSourceReturnRefundMethodReturnOriginReturnGiftCardReturnExchangeReturnExchangeLineItemReturnManualResolution