Create return · Bigblue Developers

POST/bigblue.storeapi.v1.PublicAPI/CreateReturn

Creates a return for an order. Use it when your own returns page or support tool handles the return instead of the Bigblue returns page.

On each line, send product and expected_quantity, plus return_reasons if you have them. The warehouse fills in received_quantity, damaged_quantity and quality_controls.

Request body

returnReturnFormrequired

The return to create.

ReturnForm

orderstringrequired

The order the units came from.

Pattern^[A-Za-z0-9]{12}$

warehousestringrequired

The warehouse to return the units to.

Pattern^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$

line_itemsReturnLineItem[]required

Units being returned. At least one line.

At least 1 item

external_idstring

Your own reference.

Up to 64 characters

requested_refund_methodReturnRefundMethod

How the customer wants to be refunded. The default, RETURN_REFUND_METHOD_UNSPECIFIED, means you refund the customer yourself.

idstring

Ignored. Bigblue generates the ID.

Pattern^[A-Za-z0-9]{12}RT[A-Za-z0-9]{2}$

tracking_numberstring

Ignored on create.

resolution_statusReturnResolutionStatus

Ignored on create. Use UpdateReturn.

manual_resolutionReturnManualResolution

Ignored on create. Use UpdateReturn.

Responses

200The return was created.

returnReturn

The new return with its id and status. Includes label_url if Bigblue created a return label.

400A field is invalid, for example no line items.

{
  "code": "invalid_argument",
  "msg": "return.line_items value must contain at least 1 item(s)",
  "meta": { "argument": "return.line_items" }
}

404The order or a product doesn't exist.

{ "code": "not_found", "msg": "order BGBL0K3M9XQ2 not found" }

POST/bigblue.storeapi.v1.PublicAPI/CreateReturn

Request

{
  "return": {
    "order": "BGBL0K3M9XQ2",
    "warehouse": "FR-CDG-001",
    "external_id": "rma-4471",
    "requested_refund_method": "RETURN_REFUND_METHOD_STORE_CREDIT",
    "line_items": [
      {
        "id": "rma-4471-1",
        "product": "BGBL-ESPSRT-SMAL",
        "expected_quantity": 1,
        "return_reasons": [
          {
            "type": "RETURN_REASON_TYPE_ITEM_TOO_SMALL",
            "comment": "Too small"
          }
        ]
      }
    ]
  }
}

200

{
  "return": {
    "id": "BGBL0K3M9XQ2RT01",
    "order": "BGBL0K3M9XQ2",
    "external_id": "rma-4471",
    "warehouse": "FR-CDG-001",
    "status": "RETURN_STATUS_CREATED",
    "resolution_status": "RETURN_RESOLUTION_STATUS_OPEN",
    "source": "RETURN_SOURCE_MERCHANT",
    "refund_method": "RETURN_REFUND_METHOD_STORE_CREDIT",
    "currency": "EUR",
    "label_url": "https://labels.bigblue.co/r/BGBL0K3M9XQ2RT01.pdf",
    "create_time": "2026-03-20T10:15:00Z",
    "line_items": [
      {
        "id": "rma-4471-1",
        "product": "BGBL-ESPSRT-SMAL",
        "expected_quantity": 1,
        "return_reasons": [
          {
            "type": "RETURN_REASON_TYPE_ITEM_TOO_SMALL",
            "comment": "Too small"
          }
        ]
      }
    ]
  }
}