{ "openapi": "3.1.0", "info": { "title": "Bigblue Store API", "version": "v1", "summary": "Send products, inbound shipments and orders to Bigblue.", "description": "Use the Store API to send products, inbound shipments and orders to Bigblue,\nand to read stock, tracking and returns.\n\n## Requests\n\n- Every operation is a `POST` to `/bigblue.storeapi.v1.PublicAPI/{Method}`, including\n reads. A `GET` returns `404` with the code `bad_route`.\n- There are no path or query parameters. Send all input in the JSON body.\n- A `POST` with `Content-Type: application/json` and no body counts as `{}`.\n- Operations with nothing to return send `{}`.\n\n## Responses\n\n- Field names are snake_case. Enum values are strings, such as `\"SHIPPED\"`.\n- Empty values are left out. A count of `0`, an empty string, `false` or an\n empty list doesn't appear in the response.\n- 64-bit integers are sent as strings.\n\nRequests accept snake_case or camelCase field names and ignore unknown fields. New\nfields can be added to `v1` at any time.\n\n## Money and dates\n\nAmounts are decimal strings in the main currency unit: `\"24.90\"` means 24.90\neuros. Timestamps are RFC 3339 in UTC, ending in `Z`, for example\n`2026-03-14T09:30:00Z`. Lot expiry dates use `YYYY-MM-DD`.\n\n## Rate limit\n\nEach account can make 200 requests per minute across all endpoints and API keys.\nAbove the limit, the API returns HTTP `403` with the code\n`resource_exhausted`. Use webhooks instead of polling. They don't count against\nthe limit." }, "servers": [ { "url": "https://api.bigblue.co", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Products", "description": "Products the warehouse stores and ships." }, { "name": "Bundles", "description": "Groups of up to 20 products sold as one item." }, { "name": "Inbound shipments", "description": "Deliveries of stock to a Bigblue warehouse." }, { "name": "Inventory", "description": "Stock levels per warehouse, lot and sales channel." }, { "name": "Orders", "description": "Orders to pick, pack and ship." }, { "name": "Tracking", "description": "Tracking numbers, statuses and carrier events." }, { "name": "Returns", "description": "Units returned by customers." }, { "name": "Storefront token", "description": "Short-lived tokens for browser modules." } ], "paths": { "/bigblue.storeapi.v1.PublicAPI/CreateProduct": { "post": { "operationId": "CreateProduct", "summary": "Create product", "tags": [ "Products" ], "description": "Adds a product to your catalogue. Creating a product doesn't create stock.\nStock arrives through inbound shipments.\n\nYou can't change the `id` later. It appears on orders, inbound shipments,\ninventory and webhooks.\n\nYou can't send `weight`, `width`, `height` or `depth`. The warehouse measures\nthem when it first receives the product.\n\nMore examples and notes: [Create product](/docs/store-api/products/create) in the Store API guide.\n\n> **Warning: Barcode is required**\n>\n> An empty `barcode` fails with `invalid_argument`.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateProduct \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"product\": {\n \"id\": \"BGBL-ESPSRT-SMAL\",\n \"sku\": \"ESP-SHIRT-S\",\n \"name\": \"Espresso T-shirt, Small\",\n \"description\": \"Heavyweight organic cotton tee, unisex fit.\",\n \"options\": [\n {\n \"name\": \"Size\",\n \"value\": \"Small\"\n }\n ],\n \"barcode\": \"3401579800127\",\n \"value\": {\n \"amount\": \"24.90\",\n \"currency\": \"EUR\"\n },\n \"tariff_number\": \"6109.10\",\n \"origin_country\": \"PT\",\n \"customs_description\": \"Cotton t-shirt\",\n \"name_translations\": [\n {\n \"language\": \"fr\",\n \"name\": \"T-shirt Espresso S\"\n }\n ],\n \"foldable\": true\n }\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateProduct', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"product\": {\n \"id\": \"BGBL-ESPSRT-SMAL\",\n \"sku\": \"ESP-SHIRT-S\",\n \"name\": \"Espresso T-shirt, Small\",\n \"description\": \"Heavyweight organic cotton tee, unisex fit.\",\n \"options\": [\n {\n \"name\": \"Size\",\n \"value\": \"Small\"\n }\n ],\n \"barcode\": \"3401579800127\",\n \"value\": {\n \"amount\": \"24.90\",\n \"currency\": \"EUR\"\n },\n \"tariff_number\": \"6109.10\",\n \"origin_country\": \"PT\",\n \"customs_description\": \"Cotton t-shirt\",\n \"name_translations\": [\n {\n \"language\": \"fr\",\n \"name\": \"T-shirt Espresso S\"\n }\n ],\n \"foldable\": true\n }\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateProduct\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"product\": {\n \"id\": \"BGBL-ESPSRT-SMAL\",\n \"sku\": \"ESP-SHIRT-S\",\n \"name\": \"Espresso T-shirt, Small\",\n \"description\": \"Heavyweight organic cotton tee, unisex fit.\",\n \"options\": [\n {\n \"name\": \"Size\",\n \"value\": \"Small\"\n }\n ],\n \"barcode\": \"3401579800127\",\n \"value\": {\n \"amount\": \"24.90\",\n \"currency\": \"EUR\"\n },\n \"tariff_number\": \"6109.10\",\n \"origin_country\": \"PT\",\n \"customs_description\": \"Cotton t-shirt\",\n \"name_translations\": [\n {\n \"language\": \"fr\",\n \"name\": \"T-shirt Espresso S\"\n }\n ],\n \"foldable\": True\n }\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"product\": {\n \"id\": \"BGBL-ESPSRT-SMAL\",\n \"sku\": \"ESP-SHIRT-S\",\n \"name\": \"Espresso T-shirt, Small\",\n \"description\": \"Heavyweight organic cotton tee, unisex fit.\",\n \"options\": [\n {\n \"name\": \"Size\",\n \"value\": \"Small\"\n }\n ],\n \"barcode\": \"3401579800127\",\n \"value\": {\n \"amount\": \"24.90\",\n \"currency\": \"EUR\"\n },\n \"tariff_number\": \"6109.10\",\n \"origin_country\": \"PT\",\n \"customs_description\": \"Cotton t-shirt\",\n \"name_translations\": [\n {\n \"language\": \"fr\",\n \"name\": \"T-shirt Espresso S\"\n }\n ],\n \"foldable\": true\n }\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateProduct\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" }, "examples": { "example": { "summary": "Example request", "value": { "product": { "id": "BGBL-ESPSRT-SMAL", "sku": "ESP-SHIRT-S", "name": "Espresso T-shirt, Small", "description": "Heavyweight organic cotton tee, unisex fit.", "options": [ { "name": "Size", "value": "Small" } ], "barcode": "3401579800127", "value": { "amount": "24.90", "currency": "EUR" }, "tariff_number": "6109.10", "origin_country": "PT", "customs_description": "Cotton t-shirt", "name_translations": [ { "language": "fr", "name": "T-shirt Espresso S" } ], "foldable": true } } } } } } }, "responses": { "200": { "description": "Dimensions are missing until the warehouse measures the product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductResponse" }, "examples": { "example": { "summary": "Example response", "value": { "product": { "id": "BGBL-ESPSRT-SMAL", "sku": "ESP-SHIRT-S", "name": "Espresso T-shirt, Small", "description": "Heavyweight organic cotton tee, unisex fit.", "options": [ { "name": "Size", "value": "Small" } ], "barcode": "3401579800127", "value": { "amount": "24.9", "currency": "EUR" }, "tariff_number": "6109.10", "origin_country": "PT", "customs_description": "Cotton t-shirt", "name_translations": [ { "language": "fr", "name": "T-shirt Espresso S" } ], "foldable": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/UpdateProduct": { "post": { "operationId": "UpdateProduct", "summary": "Update product", "tags": [ "Products" ], "description": "Send the whole object. Fields you leave out are cleared. Get the current\nobject, change it, then send all of it back.\n\nThese fields are updated: `name`, `sku`, `description`, `options`, `barcode`,\n`value`, `tariff_number`, `origin_country`, `customs_description`,\n`name_translations`, `non_returnable`, `foldable` and `already_packaged`.\n\nMore examples and notes: [Update product](/docs/store-api/products/update) in the Store API guide.\n\n> **Warning: Lot settings aren't updated**\n>\n> `track_lots`, `track_lot_expiry` and `lot_expiry_threshold_days` are\n> ignored, and the request still returns `200`. Change them in the Bigblue app.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateProduct \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateProduct', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateProduct\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={},\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateProduct\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/GetProduct": { "post": { "operationId": "GetProduct", "summary": "Get product", "tags": [ "Products" ], "description": "You can only look up a product by its Bigblue `id`, not by `sku` or\n`barcode`. To find products by your own reference, list them with\n`ListProducts`.\n\nMore examples and notes: [Get product](/docs/store-api/products/get) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetProduct \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"BGBL-ESPSRT-SMAL\"\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetProduct', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"BGBL-ESPSRT-SMAL\"\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetProduct\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"id\": \"BGBL-ESPSRT-SMAL\"\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"id\": \"BGBL-ESPSRT-SMAL\"\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetProduct\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProductRequest" }, "examples": { "example": { "summary": "Example request", "value": { "id": "BGBL-ESPSRT-SMAL" } } } } } }, "responses": { "200": { "description": "A received product, with measured dimensions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProductResponse" }, "examples": { "example": { "summary": "Example response", "value": { "product": { "id": "BGBL-ESPSRT-SMAL", "sku": "ESP-SHIRT-S", "name": "Espresso T-shirt, Small", "weight": 210, "width": 240, "height": 30, "depth": 180, "barcode": "3401579800127", "value": { "amount": "24.9", "currency": "EUR" }, "tariff_number": "6109.10", "origin_country": "PT", "customs_description": "Cotton t-shirt", "foldable": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/ListProducts": { "post": { "operationId": "ListProducts", "summary": "List products", "tags": [ "Products" ], "description": "Lists all products. There are no filters. Bundles aren't included.\n\nMore examples and notes: [List products](/docs/store-api/products/list) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListProducts \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"page_size\": 100\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListProducts', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"page_size\": 100\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListProducts\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"page_size\": 100\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"page_size\": 100\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListProducts\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProductsRequest" }, "examples": { "example": { "summary": "Example request", "value": { "page_size": 100 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProductsResponse" }, "examples": { "example": { "summary": "Example response", "value": { "products": [ { "id": "BGBL-ESPSRT-SMAL", "sku": "ESP-SHIRT-S", "name": "Espresso T-shirt, Small", "weight": 210, "barcode": "3401579800127", "value": { "amount": "24.9", "currency": "EUR" } }, { "id": "BGBL-ESPSRT-MEDI", "sku": "ESP-SHIRT-M", "name": "Espresso T-shirt, Medium", "weight": 225, "barcode": "3401579800134", "value": { "amount": "24.9", "currency": "EUR" } } ], "next_page_token": "ChgKFgoJcHJvZHVjdHMSCUJHQkwtRVNQ" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/DeleteProduct": { "post": { "operationId": "DeleteProduct", "summary": "Delete product", "tags": [ "Products" ], "description": "Deletes a product. A product with stock, an open inbound shipment or orders\ncan't be deleted and fails with `failed_precondition`.\n\nIf the product is part of a bundle, remove it from the bundle first.\n\nMore examples and notes: [Delete product](/docs/store-api/products/delete) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteProduct \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"BGBL-ESPSRT-SMAL\"\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteProduct', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"BGBL-ESPSRT-SMAL\"\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteProduct\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"id\": \"BGBL-ESPSRT-SMAL\"\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"id\": \"BGBL-ESPSRT-SMAL\"\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteProduct\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteProductRequest" }, "examples": { "example": { "summary": "Example request", "value": { "id": "BGBL-ESPSRT-SMAL" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteProductResponse" }, "examples": { "example": { "summary": "Example response", "value": {} } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/CreateBundle": { "post": { "operationId": "CreateBundle", "summary": "Create bundle", "tags": [ "Bundles" ], "description": "Groups existing products into a bundle you can sell as one item. Components\nmust be products. Bundles can't contain bundles.\n\nA bundle has no stock of its own. Its availability is:\n\n```\navailable = min(floor(component.available / component.quantity))\n```\n\nMore examples and notes: [Create bundle](/docs/store-api/bundles/create) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateBundle \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"bundle\": {\n \"id\": \"BGBLBU-KITSTA-2024\",\n \"display_name\": \"Starter kit: 2 mugs and 1 shirt\",\n \"components\": [\n {\n \"product\": \"BGBL-MUGCLA-WHIT\",\n \"quantity\": 2\n },\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"quantity\": 1\n }\n ],\n \"options\": [\n {\n \"name\": \"Edition\",\n \"value\": \"2024\"\n }\n ]\n }\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateBundle', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"bundle\": {\n \"id\": \"BGBLBU-KITSTA-2024\",\n \"display_name\": \"Starter kit: 2 mugs and 1 shirt\",\n \"components\": [\n {\n \"product\": \"BGBL-MUGCLA-WHIT\",\n \"quantity\": 2\n },\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"quantity\": 1\n }\n ],\n \"options\": [\n {\n \"name\": \"Edition\",\n \"value\": \"2024\"\n }\n ]\n }\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateBundle\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"bundle\": {\n \"id\": \"BGBLBU-KITSTA-2024\",\n \"display_name\": \"Starter kit: 2 mugs and 1 shirt\",\n \"components\": [\n {\n \"product\": \"BGBL-MUGCLA-WHIT\",\n \"quantity\": 2\n },\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"quantity\": 1\n }\n ],\n \"options\": [\n {\n \"name\": \"Edition\",\n \"value\": \"2024\"\n }\n ]\n }\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"bundle\": {\n \"id\": \"BGBLBU-KITSTA-2024\",\n \"display_name\": \"Starter kit: 2 mugs and 1 shirt\",\n \"components\": [\n {\n \"product\": \"BGBL-MUGCLA-WHIT\",\n \"quantity\": 2\n },\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"quantity\": 1\n }\n ],\n \"options\": [\n {\n \"name\": \"Edition\",\n \"value\": \"2024\"\n }\n ]\n }\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateBundle\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBundleRequest" }, "examples": { "example": { "summary": "Example request", "value": { "bundle": { "id": "BGBLBU-KITSTA-2024", "display_name": "Starter kit: 2 mugs and 1 shirt", "components": [ { "product": "BGBL-MUGCLA-WHIT", "quantity": 2 }, { "product": "BGBL-ESPSRT-SMAL", "quantity": 1 } ], "options": [ { "name": "Edition", "value": "2024" } ] } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBundleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/UpdateBundle": { "post": { "operationId": "UpdateBundle", "summary": "Update bundle", "tags": [ "Bundles" ], "description": "Send the whole object. Fields you leave out are cleared. Get the current\nobject, change it, then send all of it back. The `components` you send replace the existing list.\n\nMore examples and notes: [Update bundle](/docs/store-api/bundles/update) in the Store API guide.\n\n> **Warning: Availability changes immediately**\n>\n> Adding a component with little stock can drop the bundle's `available` to 0\n> right away.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateBundle \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateBundle', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateBundle\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={},\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateBundle\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBundleRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBundleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/GetBundle": { "post": { "operationId": "GetBundle", "summary": "Get bundle", "tags": [ "Bundles" ], "description": "Returns the bundle and its components. For stock, use `ListBundleInventories`.\n\nMore examples and notes: [Get bundle](/docs/store-api/bundles/get) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetBundle \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"BGBLBU-KITSTA-2024\"\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetBundle', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"BGBLBU-KITSTA-2024\"\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetBundle\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"id\": \"BGBLBU-KITSTA-2024\"\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"id\": \"BGBLBU-KITSTA-2024\"\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetBundle\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBundleRequest" }, "examples": { "example": { "summary": "Example request", "value": { "id": "BGBLBU-KITSTA-2024" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBundleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/ListBundles": { "post": { "operationId": "ListBundles", "summary": "List bundles", "tags": [ "Bundles" ], "description": "Lists all bundles. `page_size` defaults to 100.\n\nMore examples and notes: [List bundles](/docs/store-api/bundles/list) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListBundles \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"page_size\": 50\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListBundles', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"page_size\": 50\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListBundles\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"page_size\": 50\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"page_size\": 50\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListBundles\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBundlesRequest" }, "examples": { "example": { "summary": "Example request", "value": { "page_size": 50 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBundlesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/DeleteBundle": { "post": { "operationId": "DeleteBundle", "summary": "Delete bundle", "tags": [ "Bundles" ], "description": "Deletes the bundle. Its products and their stock aren't affected. Orders that\ncontain the bundle keep their line items.\n\nMore examples and notes: [Delete bundle](/docs/store-api/bundles/delete) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteBundle \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"BGBLBU-KITSTA-2024\"\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteBundle', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"BGBLBU-KITSTA-2024\"\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteBundle\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"id\": \"BGBLBU-KITSTA-2024\"\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"id\": \"BGBLBU-KITSTA-2024\"\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteBundle\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBundleRequest" }, "examples": { "example": { "summary": "Example request", "value": { "id": "BGBLBU-KITSTA-2024" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBundleResponse" }, "examples": { "example": { "summary": "Example response", "value": {} } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/CreateInboundShipment": { "post": { "operationId": "CreateInboundShipment", "summary": "Create inbound shipment", "tags": [ "Inbound shipments" ], "description": "Tells a warehouse about a delivery. Inbound shipments are the only way to add\nstock.\n\nBy default the shipment is a draft you can still edit. With `finalize: true`, it's\nsent to the warehouse right away.\n\nMore examples and notes: [Create inbound shipment](/docs/store-api/inbound-shipments/create) in the Store API guide.\n\n> **Note: Save the appointment URL**\n>\n> Only create and update return `public_appointment_url`. Get and list return\n> it empty.\n\n> **Note: Landed cost currency**\n>\n> `unit_landed_cost` uses the warehouse's valuation currency, or the default\n> currency of the warehouse's country. The response returns it as `currency`.\n\n> **Warning: Lot fields**\n>\n> Products with `track_lots` need a `lot_code`. Products with\n> `track_lot_expiry` also need a `lot_expiration_date`. If one is missing, the\n> request fails with `invalid_argument`.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateInboundShipment \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"finalize\": true,\n \"inbound_shipment\": {\n \"supplier_shipment_id\": \"PO-2026-0412\",\n \"supplier_name\": \"Coimbra Textiles\",\n \"warehouse\": \"FR-CDG-001\",\n \"expected_arrival_time\": \"2026-04-02T08:00:00Z\",\n \"carrier_name\": \"DB Schenker\",\n \"expected_load\": {\n \"pallet_load\": {\n \"homogeneous_pallet_count\": 4,\n \"heterogeneous_pallet_count\": 1,\n \"heterogeneous_pallet_homogeneous_box_count\": 18,\n \"heterogeneous_pallet_heterogeneous_box_count\": 6\n }\n },\n \"line_items\": [\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"supplier_sku\": \"CT-TEE-S\",\n \"quantity\": 600,\n \"unit_landed_cost\": \"7.35\"\n },\n {\n \"product\": \"BGBL-ESPSRT-MEDI\",\n \"supplier_sku\": \"CT-TEE-M\",\n \"quantity\": 900,\n \"unit_landed_cost\": \"7.35\"\n }\n ]\n }\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateInboundShipment', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"finalize\": true,\n \"inbound_shipment\": {\n \"supplier_shipment_id\": \"PO-2026-0412\",\n \"supplier_name\": \"Coimbra Textiles\",\n \"warehouse\": \"FR-CDG-001\",\n \"expected_arrival_time\": \"2026-04-02T08:00:00Z\",\n \"carrier_name\": \"DB Schenker\",\n \"expected_load\": {\n \"pallet_load\": {\n \"homogeneous_pallet_count\": 4,\n \"heterogeneous_pallet_count\": 1,\n \"heterogeneous_pallet_homogeneous_box_count\": 18,\n \"heterogeneous_pallet_heterogeneous_box_count\": 6\n }\n },\n \"line_items\": [\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"supplier_sku\": \"CT-TEE-S\",\n \"quantity\": 600,\n \"unit_landed_cost\": \"7.35\"\n },\n {\n \"product\": \"BGBL-ESPSRT-MEDI\",\n \"supplier_sku\": \"CT-TEE-M\",\n \"quantity\": 900,\n \"unit_landed_cost\": \"7.35\"\n }\n ]\n }\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateInboundShipment\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"finalize\": True,\n \"inbound_shipment\": {\n \"supplier_shipment_id\": \"PO-2026-0412\",\n \"supplier_name\": \"Coimbra Textiles\",\n \"warehouse\": \"FR-CDG-001\",\n \"expected_arrival_time\": \"2026-04-02T08:00:00Z\",\n \"carrier_name\": \"DB Schenker\",\n \"expected_load\": {\n \"pallet_load\": {\n \"homogeneous_pallet_count\": 4,\n \"heterogeneous_pallet_count\": 1,\n \"heterogeneous_pallet_homogeneous_box_count\": 18,\n \"heterogeneous_pallet_heterogeneous_box_count\": 6\n }\n },\n \"line_items\": [\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"supplier_sku\": \"CT-TEE-S\",\n \"quantity\": 600,\n \"unit_landed_cost\": \"7.35\"\n },\n {\n \"product\": \"BGBL-ESPSRT-MEDI\",\n \"supplier_sku\": \"CT-TEE-M\",\n \"quantity\": 900,\n \"unit_landed_cost\": \"7.35\"\n }\n ]\n }\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"finalize\": true,\n \"inbound_shipment\": {\n \"supplier_shipment_id\": \"PO-2026-0412\",\n \"supplier_name\": \"Coimbra Textiles\",\n \"warehouse\": \"FR-CDG-001\",\n \"expected_arrival_time\": \"2026-04-02T08:00:00Z\",\n \"carrier_name\": \"DB Schenker\",\n \"expected_load\": {\n \"pallet_load\": {\n \"homogeneous_pallet_count\": 4,\n \"heterogeneous_pallet_count\": 1,\n \"heterogeneous_pallet_homogeneous_box_count\": 18,\n \"heterogeneous_pallet_heterogeneous_box_count\": 6\n }\n },\n \"line_items\": [\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"supplier_sku\": \"CT-TEE-S\",\n \"quantity\": 600,\n \"unit_landed_cost\": \"7.35\"\n },\n {\n \"product\": \"BGBL-ESPSRT-MEDI\",\n \"supplier_sku\": \"CT-TEE-M\",\n \"quantity\": 900,\n \"unit_landed_cost\": \"7.35\"\n }\n ]\n }\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateInboundShipment\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboundShipmentRequest" }, "examples": { "example": { "summary": "Example request", "value": { "finalize": true, "inbound_shipment": { "supplier_shipment_id": "PO-2026-0412", "supplier_name": "Coimbra Textiles", "warehouse": "FR-CDG-001", "expected_arrival_time": "2026-04-02T08:00:00Z", "carrier_name": "DB Schenker", "expected_load": { "pallet_load": { "homogeneous_pallet_count": 4, "heterogeneous_pallet_count": 1, "heterogeneous_pallet_homogeneous_box_count": 18, "heterogeneous_pallet_heterogeneous_box_count": 6 } }, "line_items": [ { "product": "BGBL-ESPSRT-SMAL", "supplier_sku": "CT-TEE-S", "quantity": 600, "unit_landed_cost": "7.35" }, { "product": "BGBL-ESPSRT-MEDI", "supplier_sku": "CT-TEE-M", "quantity": 900, "unit_landed_cost": "7.35" } ] } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboundShipmentResponse" }, "examples": { "example": { "summary": "Example response", "value": { "inbound_shipment": { "id": "IB7K2M9XQ4P1C", "supplier_shipment_id": "PO-2026-0412", "supplier_name": "Coimbra Textiles", "warehouse": "FR-CDG-001", "expected_arrival_time": "2026-04-02T08:00:00Z", "carrier_name": "DB Schenker", "currency": "EUR", "line_items": [ { "product": "BGBL-ESPSRT-SMAL", "supplier_sku": "CT-TEE-S", "quantity": 600, "unit_landed_cost": "7.35" }, { "product": "BGBL-ESPSRT-MEDI", "supplier_sku": "CT-TEE-M", "quantity": 900, "unit_landed_cost": "7.35" } ], "status": { "code": "TRANSMITTED", "total_expected_count": 1500 }, "create_time": "2026-03-14T09:30:00Z", "public_appointment_url": "https://inbounds.bigblue.co/a/IB7K2M9XQ4P1C" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/UpdateInboundShipment": { "post": { "operationId": "UpdateInboundShipment", "summary": "Update inbound shipment", "tags": [ "Inbound shipments" ], "description": "Updates the fields listed in `update_mask`. Other fields aren't changed.\n\nAllowed values: `supplier_shipment_id`, `supplier_name`, `warehouse`,\n`expected_arrival_time`, `expected_load`, `carrier_name`, `line_items`.\n\n`line_items` replaces all existing lines, so send every line.\n\n`receive_to_order` can only be set on create. Putting it in the mask fails with\n`invalid_argument`.\n\nOnce the shipment is `ARRIVED` or later, updates fail with\n`failed_precondition`.\n\nMore examples and notes: [Update inbound shipment](/docs/store-api/inbound-shipments/update) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateInboundShipment \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"inbound_shipment\": {\n \"id\": \"IB7K2M9XQ4P1C\",\n \"expected_arrival_time\": \"2026-04-09T08:00:00Z\"\n },\n \"update_mask\": [\n \"expected_arrival_time\"\n ]\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateInboundShipment', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"inbound_shipment\": {\n \"id\": \"IB7K2M9XQ4P1C\",\n \"expected_arrival_time\": \"2026-04-09T08:00:00Z\"\n },\n \"update_mask\": [\n \"expected_arrival_time\"\n ]\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateInboundShipment\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"inbound_shipment\": {\n \"id\": \"IB7K2M9XQ4P1C\",\n \"expected_arrival_time\": \"2026-04-09T08:00:00Z\"\n },\n \"update_mask\": [\n \"expected_arrival_time\"\n ]\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"inbound_shipment\": {\n \"id\": \"IB7K2M9XQ4P1C\",\n \"expected_arrival_time\": \"2026-04-09T08:00:00Z\"\n },\n \"update_mask\": [\n \"expected_arrival_time\"\n ]\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateInboundShipment\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboundShipmentRequest" }, "examples": { "example": { "summary": "Example request", "value": { "inbound_shipment": { "id": "IB7K2M9XQ4P1C", "expected_arrival_time": "2026-04-09T08:00:00Z" }, "update_mask": [ "expected_arrival_time" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboundShipmentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/DeleteInboundShipment": { "post": { "operationId": "DeleteInboundShipment", "summary": "Delete inbound shipment", "tags": [ "Inbound shipments" ], "description": "Deletes a shipment before it arrives. Once it's `ARRIVED` or later, deleting\nfails with `failed_precondition`. To change a shipment, update it instead.\nDeleting and recreating it loses the delivery slot.\n\nMore examples and notes: [Delete inbound shipment](/docs/store-api/inbound-shipments/delete) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteInboundShipment \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"IB7K2M9XQ4P1C\"\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteInboundShipment', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"IB7K2M9XQ4P1C\"\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteInboundShipment\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"id\": \"IB7K2M9XQ4P1C\"\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"id\": \"IB7K2M9XQ4P1C\"\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/DeleteInboundShipment\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteInboundShipmentRequest" }, "examples": { "example": { "summary": "Example request", "value": { "id": "IB7K2M9XQ4P1C" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteInboundShipmentResponse" }, "examples": { "example": { "summary": "Example response", "value": {} } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/GetInboundShipment": { "post": { "operationId": "GetInboundShipment", "summary": "Get inbound shipment", "tags": [ "Inbound shipments" ], "description": "Returns the shipment with `status.line_progresses`, the units received per\nline. Compare `expected_count` with `offloaded_count + damaged_count` to find\ndifferences. Only `offloaded_count` becomes sellable stock.\n\n`appointment` is the delivery slot: the approved request if there is one,\notherwise the most recent request. Only get and list return it.\n\nMore examples and notes: [Get inbound shipment](/docs/store-api/inbound-shipments/get) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetInboundShipment \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"IB7K2M9XQ4P1C\"\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetInboundShipment', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"IB7K2M9XQ4P1C\"\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetInboundShipment\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"id\": \"IB7K2M9XQ4P1C\"\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"id\": \"IB7K2M9XQ4P1C\"\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetInboundShipment\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInboundShipmentRequest" }, "examples": { "example": { "summary": "Example request", "value": { "id": "IB7K2M9XQ4P1C" } } } } } }, "responses": { "200": { "description": "The second line is 12 units short.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInboundShipmentResponse" }, "examples": { "example": { "summary": "Example response", "value": { "inbound_shipment": { "id": "IB7K2M9XQ4P1C", "supplier_shipment_id": "PO-2026-0412", "supplier_name": "Coimbra Textiles", "warehouse": "FR-CDG-001", "expected_arrival_time": "2026-04-02T08:00:00Z", "appointment": { "status": "APPROVED", "time_slot_start_time": "2026-04-02T10:30:00Z", "time_slot_end_time": "2026-04-02T11:30:00Z", "warehouse_approval_note": "Dock 4. Driver must bring the delivery note.", "update_time": "2026-03-16T14:05:00Z" }, "carrier_name": "DB Schenker", "currency": "EUR", "status": { "code": "COMPLETE", "update_time": "2026-04-02T15:12:00Z", "total_expected_count": 1500, "total_offloaded_count": 1476, "total_damaged_count": 12, "comments": [ "12 units water damaged on pallet 3", "12 units missing vs delivery note" ], "line_progresses": [ { "product": "BGBL-ESPSRT-SMAL", "expected_count": 600, "offloaded_count": 588, "damaged_count": 12 }, { "product": "BGBL-ESPSRT-MEDI", "expected_count": 900, "offloaded_count": 888 } ] }, "create_time": "2026-03-14T09:30:00Z", "delivery_note_url": "https://docs.bigblue.co/dn/IB7K2M9XQ4P1C.pdf" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/ListInboundShipments": { "post": { "operationId": "ListInboundShipments", "summary": "List inbound shipments", "tags": [ "Inbound shipments" ], "description": "Lists inbound shipments. Filters are optional and can be combined: by\n`warehouses`, `status_codes`, `line_item_products`, `supplier_name` (contains,\ncase-insensitive) or `supplier_shipment_id`. To filter by date, filter on\n`expected_arrival_time` in your code. Each shipment includes its `appointment`.\n\nMore examples and notes: [List inbound shipments](/docs/store-api/inbound-shipments/list) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListInboundShipments \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"warehouses\": [\n \"FR-CDG-001\"\n ],\n \"status_codes\": [\n \"ARRIVED\",\n \"COMPLETE\"\n ],\n \"page_size\": 50\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListInboundShipments', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"warehouses\": [\n \"FR-CDG-001\"\n ],\n \"status_codes\": [\n \"ARRIVED\",\n \"COMPLETE\"\n ],\n \"page_size\": 50\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListInboundShipments\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"warehouses\": [\n \"FR-CDG-001\"\n ],\n \"status_codes\": [\n \"ARRIVED\",\n \"COMPLETE\"\n ],\n \"page_size\": 50\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"warehouses\": [\n \"FR-CDG-001\"\n ],\n \"status_codes\": [\n \"ARRIVED\",\n \"COMPLETE\"\n ],\n \"page_size\": 50\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListInboundShipments\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInboundShipmentsRequest" }, "examples": { "example": { "summary": "Example request", "value": { "warehouses": [ "FR-CDG-001" ], "status_codes": [ "ARRIVED", "COMPLETE" ], "page_size": 50 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInboundShipmentsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/ListInventories": { "post": { "operationId": "ListInventories", "summary": "List inventories", "tags": [ "Inventory" ], "description": "Returns one row per product and warehouse. Inventory is read-only.\n\n`available` is what you can sell now. `in_warehouse` includes units reserved for\nunshipped orders, so reserved units are `in_warehouse - available`. Damaged,\nquality control and expired units aren't in `in_warehouse`.\n\nBoth filters are optional. `page_size` can be up to 1000.\n\nMore examples and notes: [List inventories](/docs/store-api/inventory/list-inventories) in the Store API guide.\n\n> **Note: Lots**\n>\n> Lot counts are only included when lot tracking is on and the product has\n> `track_lots`. Up to 100 lots per row. Lots have no `available` count.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListInventories \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"product\": \"BGBL-COFBEA-1KGX\",\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 100\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListInventories', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"product\": \"BGBL-COFBEA-1KGX\",\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 100\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListInventories\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"product\": \"BGBL-COFBEA-1KGX\",\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 100\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"product\": \"BGBL-COFBEA-1KGX\",\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 100\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListInventories\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInventoriesRequest" }, "examples": { "example": { "summary": "Example request", "value": { "product": "BGBL-COFBEA-1KGX", "warehouse": "FR-CDG-001", "page_size": 100 } } } } } }, "responses": { "200": { "description": "All units in lot L2026-04 are in quality control, so they are not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInventoriesResponse" }, "examples": { "example": { "summary": "Example response", "value": { "inventories": [ { "product": "BGBL-COFBEA-1KGX", "warehouse": "FR-CDG-001", "available": 348, "in_warehouse": 372, "damaged": 4, "quality_control": 480, "expired": 12, "lots": [ { "lot_code": "L2026-02", "lot_expiration_date": "2027-02-28", "lot_expiration_time": "2027-02-28T00:00:00Z", "in_warehouse": 372, "damaged": 4, "expired": 12 }, { "lot_code": "L2026-04", "lot_expiration_date": "2027-04-30", "lot_expiration_time": "2027-04-30T00:00:00Z", "quality_control": 480 } ] } ], "next_page_token": "ChwKGgoLaW52ZW50b3J5EgtCR0JMLUNPRkJFQQ" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/ListBundleInventories": { "post": { "operationId": "ListBundleInventories", "summary": "List bundle inventories", "tags": [ "Inventory" ], "description": "Returns one row per bundle and warehouse, calculated from the components:\n\n```\navailable = min(floor(component.available / component.quantity))\nin_warehouse = min(floor(component.in_warehouse / component.quantity))\n```\n\nYou can filter by warehouse but not by bundle.\n\nMore examples and notes: [List bundle inventories](/docs/store-api/inventory/list-bundle-inventories) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListBundleInventories \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 100\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListBundleInventories', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 100\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListBundleInventories\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 100\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 100\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListBundleInventories\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBundleInventoriesRequest" }, "examples": { "example": { "summary": "Example request", "value": { "warehouse": "FR-CDG-001", "page_size": 100 } } } } } }, "responses": { "200": { "description": "The shirt limits the bundle to 3.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBundleInventoriesResponse" }, "examples": { "example": { "summary": "Example response", "value": { "bundle_inventories": [ { "bundle": "BGBLBU-KITSTA-2024", "warehouse": "FR-CDG-001", "available": 3, "in_warehouse": 5 } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/CreateOrder": { "post": { "operationId": "CreateOrder", "summary": "Create order", "tags": [ "Orders" ], "description": "Creates an order. If you don't send an `id`, Bigblue generates one. Send your\nown so that a retry returns `already_exists` instead of creating a duplicate.\n\nThe response has no status, packages or tracking yet. Use `GetOrder` later.\n\nYour API key's integration decides whether orders go to the warehouse\nautomatically. If auto-fulfillment is off, the `auto_fulfill_*` fields are\nignored and the order waits until it's sent from the Bigblue app.\n\nMore examples and notes: [Create order](/docs/store-api/orders/create) in the Store API guide.\n\n> **Warning: B2B templates need b2b: true**\n>\n> `b2b_fulfillment_instructions_template` without `b2b: true` fails with `invalid_argument`.\n\n> **Warning: PO numbers must be ASCII**\n>\n> A `customer_order_id` longer than 20 characters fails with `invalid_argument`.\n> One with non-ASCII characters is accepted, but the order isn't prepared until you\n> correct it with `UpdateOrder`.\n\n> **Note: Choosing a lot**\n>\n> Set `lot_code` or `lot_expiration_days_range_rule` on a line, not both. If\n> you set neither, the warehouse picks the lot that expires first. Neither works on\n> bundle lines.\n\n> **Note: Discounts**\n>\n> A line's `discount` is the total for the line, not per unit.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateOrder \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"order\": {\n \"id\": \"BGBL0K3M9XQ2\",\n \"external_id\": \"web-10231\",\n \"language\": \"fr\",\n \"currency\": \"EUR\",\n \"shipping_address\": {\n \"first_name\": \"Camille\",\n \"last_name\": \"Bernard\",\n \"email\": \"camille@example.com\",\n \"phone\": \"+33612345678\",\n \"line1\": \"12 rue de Rivoli\",\n \"city\": \"Paris\",\n \"postal\": \"75004\",\n \"country\": \"FR\"\n },\n \"line_items\": [\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"quantity\": 2,\n \"unit_price\": \"24.90\",\n \"unit_tax\": \"4.15\",\n \"discount\": \"5.00\"\n }\n ],\n \"shipping_price\": \"4.90\",\n \"shipping_tax\": \"0.82\",\n \"shipping_method\": \"Standard\",\n \"external_order_url\": \"https://shop.example.com/admin/orders/10231\"\n }\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateOrder', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"order\": {\n \"id\": \"BGBL0K3M9XQ2\",\n \"external_id\": \"web-10231\",\n \"language\": \"fr\",\n \"currency\": \"EUR\",\n \"shipping_address\": {\n \"first_name\": \"Camille\",\n \"last_name\": \"Bernard\",\n \"email\": \"camille@example.com\",\n \"phone\": \"+33612345678\",\n \"line1\": \"12 rue de Rivoli\",\n \"city\": \"Paris\",\n \"postal\": \"75004\",\n \"country\": \"FR\"\n },\n \"line_items\": [\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"quantity\": 2,\n \"unit_price\": \"24.90\",\n \"unit_tax\": \"4.15\",\n \"discount\": \"5.00\"\n }\n ],\n \"shipping_price\": \"4.90\",\n \"shipping_tax\": \"0.82\",\n \"shipping_method\": \"Standard\",\n \"external_order_url\": \"https://shop.example.com/admin/orders/10231\"\n }\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateOrder\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"order\": {\n \"id\": \"BGBL0K3M9XQ2\",\n \"external_id\": \"web-10231\",\n \"language\": \"fr\",\n \"currency\": \"EUR\",\n \"shipping_address\": {\n \"first_name\": \"Camille\",\n \"last_name\": \"Bernard\",\n \"email\": \"camille@example.com\",\n \"phone\": \"+33612345678\",\n \"line1\": \"12 rue de Rivoli\",\n \"city\": \"Paris\",\n \"postal\": \"75004\",\n \"country\": \"FR\"\n },\n \"line_items\": [\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"quantity\": 2,\n \"unit_price\": \"24.90\",\n \"unit_tax\": \"4.15\",\n \"discount\": \"5.00\"\n }\n ],\n \"shipping_price\": \"4.90\",\n \"shipping_tax\": \"0.82\",\n \"shipping_method\": \"Standard\",\n \"external_order_url\": \"https://shop.example.com/admin/orders/10231\"\n }\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"order\": {\n \"id\": \"BGBL0K3M9XQ2\",\n \"external_id\": \"web-10231\",\n \"language\": \"fr\",\n \"currency\": \"EUR\",\n \"shipping_address\": {\n \"first_name\": \"Camille\",\n \"last_name\": \"Bernard\",\n \"email\": \"camille@example.com\",\n \"phone\": \"+33612345678\",\n \"line1\": \"12 rue de Rivoli\",\n \"city\": \"Paris\",\n \"postal\": \"75004\",\n \"country\": \"FR\"\n },\n \"line_items\": [\n {\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"quantity\": 2,\n \"unit_price\": \"24.90\",\n \"unit_tax\": \"4.15\",\n \"discount\": \"5.00\"\n }\n ],\n \"shipping_price\": \"4.90\",\n \"shipping_tax\": \"0.82\",\n \"shipping_method\": \"Standard\",\n \"external_order_url\": \"https://shop.example.com/admin/orders/10231\"\n }\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateOrder\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" }, "examples": { "example": { "summary": "Example request", "value": { "order": { "id": "BGBL0K3M9XQ2", "external_id": "web-10231", "language": "fr", "currency": "EUR", "shipping_address": { "first_name": "Camille", "last_name": "Bernard", "email": "camille@example.com", "phone": "+33612345678", "line1": "12 rue de Rivoli", "city": "Paris", "postal": "75004", "country": "FR" }, "line_items": [ { "product": "BGBL-ESPSRT-SMAL", "quantity": 2, "unit_price": "24.90", "unit_tax": "4.15", "discount": "5.00" } ], "shipping_price": "4.90", "shipping_tax": "0.82", "shipping_method": "Standard", "external_order_url": "https://shop.example.com/admin/orders/10231" } } } } } } }, "responses": { "200": { "description": "No status, packages or tracking yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" }, "examples": { "example": { "summary": "Example response", "value": { "order": { "id": "BGBL0K3M9XQ2", "external_id": "web-10231", "store": "i_bgbl0001", "submit_time": "2026-03-14T09:30:00Z", "language": "fr", "currency": "EUR", "shipping_address": { "first_name": "Camille", "last_name": "Bernard", "email": "camille@example.com", "phone": "+33612345678", "line1": "12 rue de Rivoli", "city": "Paris", "postal": "75004", "country": "FR" }, "line_items": [ { "product": "BGBL-ESPSRT-SMAL", "quantity": 2, "unit_price": "24.9", "unit_tax": "4.15", "discount": "5" } ], "shipping_price": "4.9", "shipping_tax": "0.82", "additional_tax": "0", "additional_discount": "0", "total": "58.82", "shipping_method": "Standard", "external_order_url": "https://shop.example.com/admin/orders/10231" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/UpdateOrder": { "post": { "operationId": "UpdateOrder", "summary": "Update order", "tags": [ "Orders" ], "description": "Send the whole object. Fields you leave out are cleared. Get the current\nobject, change it, then send all of it back.\n\nThese fields are updated: `shipping_address`, `billing_address`, `line_items`,\n`shipping_price`, `shipping_tax`, `additional_tax`, `additional_discount`,\n`shipping_method`, `b2b`, `external_order_url` and `customer_order_id`. The B2B\ntemplate is updated if it changed. The `auto_fulfill_*` fields are ignored.\n\nYou can update an order while it's `PENDING` or `BACKORDER`. After that, updates\nfail with `failed_precondition`.\n\nMore examples and notes: [Update order](/docs/store-api/orders/update) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateOrder \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateOrder', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateOrder\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={},\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateOrder\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/CancelOrder": { "post": { "operationId": "CancelOrder", "summary": "Cancel order", "tags": [ "Orders" ], "description": "Cancels an order that's `PENDING` or `BACKORDER`. If it's already picked or\nshipped, the request fails with `failed_precondition`. Create a return instead.\n\nGet the order afterwards to confirm the status. Reserved stock becomes available\nagain. A cancelled order can't be restored.\n\nMore examples and notes: [Cancel order](/docs/store-api/orders/cancel) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CancelOrder \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"BGBL0K3M9XQ2\",\n \"reason\": \"Customer cancelled within the 30-minute grace period\"\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CancelOrder', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"BGBL0K3M9XQ2\",\n \"reason\": \"Customer cancelled within the 30-minute grace period\"\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CancelOrder\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"id\": \"BGBL0K3M9XQ2\",\n \"reason\": \"Customer cancelled within the 30-minute grace period\"\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"id\": \"BGBL0K3M9XQ2\",\n \"reason\": \"Customer cancelled within the 30-minute grace period\"\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CancelOrder\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderRequest" }, "examples": { "example": { "summary": "Example request", "value": { "id": "BGBL0K3M9XQ2", "reason": "Customer cancelled within the 30-minute grace period" } } } } } }, "responses": { "200": { "description": "Get the order to confirm the new status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderResponse" }, "examples": { "example": { "summary": "Example response", "value": {} } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/GetOrder": { "post": { "operationId": "GetOrder", "summary": "Get order", "tags": [ "Orders" ], "description": "Returns the order with its status, packages and tracking.\n\nIf an order has several parcels, `tracking_number` and `tracking_url` belong to\nthe parcel furthest along. Use `ListTrackings` for every parcel.\n\nYou can only look up orders by Bigblue `id`. To use your own reference, call\n`ListTrackings` with `external_order`.\n\nA bundle line stays a bundle in `line_items`. Its components are listed in\n`shipped_packages[].items`.\n\nMore examples and notes: [Get order](/docs/store-api/orders/get) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetOrder \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"BGBL0K3M9XQ2\"\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetOrder', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"BGBL0K3M9XQ2\"\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetOrder\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"id\": \"BGBL0K3M9XQ2\"\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"id\": \"BGBL0K3M9XQ2\"\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetOrder\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderRequest" }, "examples": { "example": { "summary": "Example request", "value": { "id": "BGBL0K3M9XQ2" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderResponse" }, "examples": { "example": { "summary": "Example response", "value": { "order": { "id": "BGBL0K3M9XQ2", "external_id": "web-10231", "store": "i_bgbl0001", "submit_time": "2026-03-14T09:30:00Z", "language": "fr", "currency": "EUR", "shipping_address": { "first_name": "Camille", "last_name": "Bernard", "email": "camille@example.com", "line1": "12 rue de Rivoli", "city": "Paris", "postal": "75004", "country": "FR" }, "line_items": [ { "product": "BGBL-ESPSRT-SMAL", "quantity": 2, "unit_price": "24.9", "unit_tax": "4.15", "discount": "5" } ], "shipping_price": "4.9", "shipping_tax": "0.82", "total": "58.82", "shipping_method": "Standard", "status": { "code": "SHIPPED", "message": "Handed over to the carrier" }, "tracking_number": "6A12345678901", "tracking_url": "https://track.bigblue.co/BGBL0K3M9XQ2?postal=75004", "shipped_packages": [ { "id": "BGBL0K3M9XQ2F1P1", "tracking_number": "6A12345678901", "weight": 480, "items": [ { "product": "BGBL-ESPSRT-SMAL", "quantity": 2 } ] } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/ListOrders": { "post": { "operationId": "ListOrders", "summary": "List orders", "tags": [ "Orders" ], "description": "Lists orders with their status, packages and tracking. Filters are optional and\ncan be combined. `via_api: true` returns only orders created by the calling key's\nintegration. `page_size` defaults to 100.\n\nA page can have fewer orders than `page_size`. Keep paging while\n`next_page_token` is set.\n\nMore examples and notes: [List orders](/docs/store-api/orders/list) in the Store API guide.\n\n> **Warning: This endpoint is slow**\n>\n> Bigblue loads fulfillments and trackings for every order on the page. Use long\n> timeouts, and use the order status webhook instead of polling.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListOrders \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"via_api\": true,\n \"date_range\": {\n \"from\": \"2026-03-13T00:00:00Z\",\n \"to\": \"2026-03-14T00:00:00Z\"\n },\n \"page_size\": 100\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListOrders', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"via_api\": true,\n \"date_range\": {\n \"from\": \"2026-03-13T00:00:00Z\",\n \"to\": \"2026-03-14T00:00:00Z\"\n },\n \"page_size\": 100\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListOrders\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"via_api\": True,\n \"date_range\": {\n \"from\": \"2026-03-13T00:00:00Z\",\n \"to\": \"2026-03-14T00:00:00Z\"\n },\n \"page_size\": 100\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"via_api\": true,\n \"date_range\": {\n \"from\": \"2026-03-13T00:00:00Z\",\n \"to\": \"2026-03-14T00:00:00Z\"\n },\n \"page_size\": 100\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListOrders\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrdersRequest" }, "examples": { "example": { "summary": "Example request", "value": { "via_api": true, "date_range": { "from": "2026-03-13T00:00:00Z", "to": "2026-03-14T00:00:00Z" }, "page_size": 100 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrdersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/ListOrderTickets": { "post": { "operationId": "ListOrderTickets", "summary": "List order tickets", "tags": [ "Orders" ], "description": "Lists the support tickets for an order. Send the order ID as `reference`.\nTickets with `ORDER_TICKET_STATUS_AWAITING_YOUR_REPLY` need an answer in the\nBigblue app. `page_size` defaults to 100.\n\nMore examples and notes: [List order tickets](/docs/store-api/orders/list-tickets) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListOrderTickets \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"reference\": \"BGBL0K3M9XQ2\",\n \"page_size\": 50\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListOrderTickets', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"reference\": \"BGBL0K3M9XQ2\",\n \"page_size\": 50\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListOrderTickets\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"reference\": \"BGBL0K3M9XQ2\",\n \"page_size\": 50\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"reference\": \"BGBL0K3M9XQ2\",\n \"page_size\": 50\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListOrderTickets\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrderTicketsRequest" }, "examples": { "example": { "summary": "Example request", "value": { "reference": "BGBL0K3M9XQ2", "page_size": 50 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrderTicketsResponse" }, "examples": { "example": { "summary": "Example response", "value": { "tickets": [ { "id": "2mQ8sT4vXb1nR7yK0jL9cW3dH5f", "reference": "BGBL0K3M9XQ2", "subject": "Items are missing", "status": "ORDER_TICKET_STATUS_AWAITING_YOUR_REPLY", "create_time": "2026-03-18T11:02:00Z", "update_time": "2026-03-19T08:41:00Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/ListAllocationInventories": { "post": { "operationId": "ListAllocationInventories", "summary": "List allocation inventories", "tags": [ "Inventory" ], "description": "Returns the stock allocated to each sales channel in a warehouse, and the stock\nnot allocated. Rows include products and bundles. `warehouse` is required and\n`page_size` can be up to 5000.\n\nMore examples and notes: [List allocation inventories](/docs/store-api/inventory/list-allocation-inventories) in the Store API guide.\n\n> **Warning: Quantities can be negative**\n>\n> In `MIN` mode, when backorders exceed stock, `available_quantity` can be\n> negative. Use `Math.max(0, quantity)` before sending it to a storefront.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListAllocationInventories \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 1000\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListAllocationInventories', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 1000\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListAllocationInventories\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 1000\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"warehouse\": \"FR-CDG-001\",\n \"page_size\": 1000\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListAllocationInventories\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAllocationInventoriesRequest" }, "examples": { "example": { "summary": "Example request", "value": { "warehouse": "FR-CDG-001", "page_size": 1000 } } } } } }, "responses": { "200": { "description": "250 units for the website, 100 for the marketplace, 62 not allocated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAllocationInventoriesResponse" }, "examples": { "example": { "summary": "Example response", "value": { "allocation_inventories": [ { "warehouse": "FR-CDG-001", "product": "BGBL-ESPSRT-SMAL", "product_sku": "ESP-SHIRT-S", "shop_inventory_location_quantities": [ { "inventory_location": { "shop": "sh_1a2b3c4d" }, "available_quantity": 250 }, { "inventory_location": { "shop": "am_9f8e7d6c" }, "available_quantity": 100 } ], "remaining_available_quantity": 62 } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/ListTrackings": { "post": { "operationId": "ListTrackings", "summary": "List trackings", "tags": [ "Tracking" ], "description": "Returns all trackings for one identifier. Set exactly one of `order_id`,\n`tracking_number` or `external_order`. An empty request fails with\n`invalid_argument`.\n\n- `tracking_number` matches the number printed on the label.\n- `order_id` returns one tracking per parcel, without cancelled fulfillments.\n- `external_order` finds the order by your reference. No match returns an empty\n response.\n\nEvents are sorted newest first. This endpoint isn't paginated.\n\nMore examples and notes: [List trackings](/docs/store-api/tracking/list-trackings) in the Store API guide.\n\n> **Note: Returning parcels**\n>\n> An order shows `DELIVERED` for a delivered parcel and a returning one. The\n> tracking status shows `DELIVERED` or `RETURNING`.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListTrackings \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"order_id\": \"BGBL0K3M9XQ2\"\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListTrackings', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"order_id\": \"BGBL0K3M9XQ2\"\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListTrackings\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"order_id\": \"BGBL0K3M9XQ2\"\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"order_id\": \"BGBL0K3M9XQ2\"\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListTrackings\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTrackingsRequest" }, "examples": { "example": { "summary": "Example request", "value": { "order_id": "BGBL0K3M9XQ2" } } } } } }, "responses": { "200": { "description": "Events are sorted newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTrackingsResponse" }, "examples": { "example": { "summary": "Example response", "value": { "trackings": [ { "tracking_number": "6A12345678901", "carrier_service": "colissimo-fr-home", "tracking_url": "https://track.bigblue.co/BGBL0K3M9XQ2?postal=75004", "update_time": "2026-03-17T09:12:00Z", "status": { "code": "DELIVERED", "message": "Colis livré" }, "events": [ { "status_code": "DELIVERED", "message": "Colis livré", "timestamp": "2026-03-17T09:12:00Z" }, { "status_code": "OUT_FOR_DELIVERY", "message": "Votre colis est en cours de livraison", "timestamp": "2026-03-17T06:40:00Z" }, { "status_code": "IN_TRANSIT", "message": "Votre colis est arrivé sur la plateforme de distribution", "timestamp": "2026-03-16T22:05:00Z" }, { "status_code": "LABEL_CREATED", "message": "Étiquette créée", "timestamp": "2026-03-15T16:20:00Z" } ] } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/GetStorefrontAccessToken": { "post": { "operationId": "GetStorefrontAccessToken", "summary": "Get storefront access token", "tags": [ "Storefront token" ], "description": "Returns a short-lived token for Bigblue modules that run in the browser, such as\nthe pickup point picker. The request has no fields. You can send an empty body.\n\nMore examples and notes: [Storefront token](/docs/store-api/storefront-access-token) in the Store API guide.\n\n> **Warning: Keep your API key on the server**\n>\n> Get the token on your server and pass only the token to the page. Reuse it until\n> shortly before it expires.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetStorefrontAccessToken \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetStorefrontAccessToken', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetStorefrontAccessToken\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={},\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetStorefrontAccessToken\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "description": "No arguments. Send `{}`, or an empty body with a JSON content type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetStorefrontAccessTokenRequest" }, "examples": { "example": { "summary": "Example request", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetStorefrontAccessTokenResponse" }, "examples": { "example": { "summary": "Example response", "value": { "token": "sft_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c", "expiry_time": "2026-03-14T10:30:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/CreateReturn": { "post": { "operationId": "CreateReturn", "summary": "Create return", "tags": [ "Returns" ], "description": "Creates a return for an order. On each line, send `product` and\n`expected_quantity`, plus `return_reasons` if you have them. The warehouse fills\nin the received quantities and inspection results.\n\nMore examples and notes: [Create return](/docs/store-api/returns/create) in the Store API guide.\n\n> **Warning: Some fields are ignored**\n>\n> Only `order`, `warehouse`, `line_items`, `external_id` and\n> `requested_refund_method` are used. Set the resolution with `UpdateReturn`.\n\n> **Note: Two statuses**\n>\n> `status` is where the parcel is. `resolution_status` is whether the refund is\n> settled.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateReturn \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"return\": {\n \"order\": \"BGBL0K3M9XQ2\",\n \"warehouse\": \"FR-CDG-001\",\n \"external_id\": \"rma-4471\",\n \"requested_refund_method\": \"RETURN_REFUND_METHOD_STORE_CREDIT\",\n \"line_items\": [\n {\n \"id\": \"rma-4471-1\",\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"expected_quantity\": 1,\n \"return_reasons\": [\n {\n \"type\": \"RETURN_REASON_TYPE_ITEM_TOO_SMALL\",\n \"comment\": \"Runs small, needs a medium\"\n }\n ]\n }\n ]\n }\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateReturn', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"return\": {\n \"order\": \"BGBL0K3M9XQ2\",\n \"warehouse\": \"FR-CDG-001\",\n \"external_id\": \"rma-4471\",\n \"requested_refund_method\": \"RETURN_REFUND_METHOD_STORE_CREDIT\",\n \"line_items\": [\n {\n \"id\": \"rma-4471-1\",\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"expected_quantity\": 1,\n \"return_reasons\": [\n {\n \"type\": \"RETURN_REASON_TYPE_ITEM_TOO_SMALL\",\n \"comment\": \"Runs small, needs a medium\"\n }\n ]\n }\n ]\n }\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateReturn\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"return\": {\n \"order\": \"BGBL0K3M9XQ2\",\n \"warehouse\": \"FR-CDG-001\",\n \"external_id\": \"rma-4471\",\n \"requested_refund_method\": \"RETURN_REFUND_METHOD_STORE_CREDIT\",\n \"line_items\": [\n {\n \"id\": \"rma-4471-1\",\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"expected_quantity\": 1,\n \"return_reasons\": [\n {\n \"type\": \"RETURN_REASON_TYPE_ITEM_TOO_SMALL\",\n \"comment\": \"Runs small, needs a medium\"\n }\n ]\n }\n ]\n }\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"return\": {\n \"order\": \"BGBL0K3M9XQ2\",\n \"warehouse\": \"FR-CDG-001\",\n \"external_id\": \"rma-4471\",\n \"requested_refund_method\": \"RETURN_REFUND_METHOD_STORE_CREDIT\",\n \"line_items\": [\n {\n \"id\": \"rma-4471-1\",\n \"product\": \"BGBL-ESPSRT-SMAL\",\n \"expected_quantity\": 1,\n \"return_reasons\": [\n {\n \"type\": \"RETURN_REASON_TYPE_ITEM_TOO_SMALL\",\n \"comment\": \"Runs small, needs a medium\"\n }\n ]\n }\n ]\n }\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateReturn\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReturnRequest" }, "examples": { "example": { "summary": "Example request", "value": { "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": "Runs small, needs a medium" } ] } ] } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReturnResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/UpdateReturn": { "post": { "operationId": "UpdateReturn", "summary": "Update return", "tags": [ "Returns" ], "description": "Updates the return's resolution. You can't change line items, the warehouse or\nthe parcel status.\n\nAllowed `update_mask` values: `resolution_status`, `manual_resolution`.\n\nMore examples and notes: [Update return](/docs/store-api/returns/update) in the Store API guide.\n\n> **Warning: Always send resolution_status**\n>\n> `resolution_status` is updated even when it's not in `update_mask`. Send the\n> current value if you only want to add a note.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateReturn \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"return\": {\n \"id\": \"BGBL0K3M9XQ2RT01\",\n \"resolution_status\": \"RETURN_RESOLUTION_STATUS_CLOSED\",\n \"manual_resolution\": {\n \"refund_method\": \"RETURN_REFUND_METHOD_MANUAL_OTHER\",\n \"note\": \"Refunded 24.90 EUR to the original card\"\n }\n },\n \"update_mask\": [\n \"resolution_status\",\n \"manual_resolution\"\n ]\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateReturn', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"return\": {\n \"id\": \"BGBL0K3M9XQ2RT01\",\n \"resolution_status\": \"RETURN_RESOLUTION_STATUS_CLOSED\",\n \"manual_resolution\": {\n \"refund_method\": \"RETURN_REFUND_METHOD_MANUAL_OTHER\",\n \"note\": \"Refunded 24.90 EUR to the original card\"\n }\n },\n \"update_mask\": [\n \"resolution_status\",\n \"manual_resolution\"\n ]\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateReturn\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"return\": {\n \"id\": \"BGBL0K3M9XQ2RT01\",\n \"resolution_status\": \"RETURN_RESOLUTION_STATUS_CLOSED\",\n \"manual_resolution\": {\n \"refund_method\": \"RETURN_REFUND_METHOD_MANUAL_OTHER\",\n \"note\": \"Refunded 24.90 EUR to the original card\"\n }\n },\n \"update_mask\": [\n \"resolution_status\",\n \"manual_resolution\"\n ]\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"return\": {\n \"id\": \"BGBL0K3M9XQ2RT01\",\n \"resolution_status\": \"RETURN_RESOLUTION_STATUS_CLOSED\",\n \"manual_resolution\": {\n \"refund_method\": \"RETURN_REFUND_METHOD_MANUAL_OTHER\",\n \"note\": \"Refunded 24.90 EUR to the original card\"\n }\n },\n \"update_mask\": [\n \"resolution_status\",\n \"manual_resolution\"\n ]\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/UpdateReturn\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReturnRequest" }, "examples": { "example": { "summary": "Example request", "value": { "return": { "id": "BGBL0K3M9XQ2RT01", "resolution_status": "RETURN_RESOLUTION_STATUS_CLOSED", "manual_resolution": { "refund_method": "RETURN_REFUND_METHOD_MANUAL_OTHER", "note": "Refunded 24.90 EUR to the original card" } }, "update_mask": [ "resolution_status", "manual_resolution" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReturnResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/GetReturn": { "post": { "operationId": "GetReturn", "summary": "Get return", "tags": [ "Returns" ], "description": "Returns the return with received quantities and inspection results.\n`received_quantity` includes damaged units. Units that go back into stock are\n`received_quantity - damaged_quantity`.\n\nMore examples and notes: [Get return](/docs/store-api/returns/get) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetReturn \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"BGBL0K3M9XQ2RT01\"\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetReturn', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"BGBL0K3M9XQ2RT01\"\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetReturn\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"id\": \"BGBL0K3M9XQ2RT01\"\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"id\": \"BGBL0K3M9XQ2RT01\"\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/GetReturn\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReturnRequest" }, "examples": { "example": { "summary": "Example request", "value": { "id": "BGBL0K3M9XQ2RT01" } } } } } }, "responses": { "200": { "description": "One inspection entry per unit. The first unit passed, so its entry is empty. The second is damaged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReturnResponse" }, "examples": { "example": { "summary": "Example response", "value": { "return": { "id": "BGBL0K3M9XQ2RT01", "order": "BGBL0K3M9XQ2", "warehouse": "FR-CDG-001", "status": "RETURN_STATUS_RETURNED", "resolution_status": "RETURN_RESOLUTION_STATUS_ACTION_REQUIRED", "source": "RETURN_SOURCE_CUSTOMER", "currency": "EUR", "return_time": "2026-03-23T09:40:00Z", "line_items": [ { "product": "BGBL-ESPSRT-SMAL", "expected_quantity": 2, "received_quantity": 2, "damaged_quantity": 1, "quality_controls": [ {}, { "damaged_reasons": [ "RETURN_DAMAGED_REASON_DAMAGED_PRODUCT" ], "images": [ { "url": "https://qc.bigblue.co/i/8f3a91.jpg" } ] } ] } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/bigblue.storeapi.v1.PublicAPI/ListReturns": { "post": { "operationId": "ListReturns", "summary": "List returns", "tags": [ "Returns" ], "description": "Lists returns for one order or a creation date range. If `order` is set, the\ndate range is ignored. With neither, lists all returns.\n\n`date_range` filters on `create_time`. To filter by reception date, use\n`return_time` in your code.\n\nMore examples and notes: [List returns](/docs/store-api/returns/list) in the Store API guide.", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListReturns \\\n -H \"Authorization: Bearer $BIGBLUE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"date_range\": {\n \"from\": \"2026-03-16T00:00:00Z\",\n \"to\": \"2026-03-23T00:00:00Z\"\n },\n \"page_size\": 100\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const res = await fetch('https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListReturns', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.BIGBLUE_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"date_range\": {\n \"from\": \"2026-03-16T00:00:00Z\",\n \"to\": \"2026-03-23T00:00:00Z\"\n },\n \"page_size\": 100\n }),\n});\n\nconst data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListReturns\",\n headers={\"Authorization\": f\"Bearer {os.environ['BIGBLUE_API_KEY']}\"},\n json={\n \"date_range\": {\n \"from\": \"2026-03-16T00:00:00Z\",\n \"to\": \"2026-03-23T00:00:00Z\"\n },\n \"page_size\": 100\n },\n)\ndata = res.json()" }, { "lang": "go", "label": "Go", "source": "body := strings.NewReader(`{\n \"date_range\": {\n \"from\": \"2026-03-16T00:00:00Z\",\n \"to\": \"2026-03-23T00:00:00Z\"\n },\n \"page_size\": 100\n}`)\n\nreq, _ := http.NewRequest(\"POST\", \"https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListReturns\", body)\nreq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"BIGBLUE_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\n\nres, err := http.DefaultClient.Do(req)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReturnsRequest" }, "examples": { "example": { "summary": "Example request", "value": { "date_range": { "from": "2026-03-16T00:00:00Z", "to": "2026-03-23T00:00:00Z" }, "page_size": 100 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReturnsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key from an integration in the Bigblue app, sent as `Authorization: Bearer `. Each key belongs to one account and one integration." } }, "schemas": { "DateRange": { "type": "object", "description": "DateRange is used to specify a date range (or time range), with a `from` field and a `to` field.", "properties": { "from": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "Start, RFC 3339 UTC, for example `2026-03-01T00:00:00Z`." }, "to": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "End, RFC 3339 UTC." } } }, "InboundShipment": { "type": "object", "description": "InboundShipment is used to store inbound shipment information.", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{13}$", "description": "Bigblue inbound shipment ID." }, "supplier_shipment_id": { "type": "string", "minLength": 1, "description": "Your or your supplier's reference for the shipment. Shown to warehouse staff." }, "supplier_name": { "type": "string", "minLength": 1, "description": "Who is sending the goods." }, "warehouse": { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$", "description": "Destination warehouse, for example `FR-CDG-001`." }, "expected_arrival_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "Expected arrival, in RFC 3339 UTC: `2026-04-02T08:00:00Z`." }, "expected_pallet_count": { "type": "integer", "format": "int32", "deprecated": true, "description": "Use `expected_load` instead." }, "expected_box_count": { "type": "integer", "format": "int32", "deprecated": true, "description": "Use `expected_load` instead." }, "expected_load": { "$ref": "#/components/schemas/InboundShipmentLoad", "description": "How the goods are packed: boxes, pallets or a container." }, "appointment_time": { "type": "string", "deprecated": true, "description": "Use `appointment.time_slot_start_time` instead." }, "carrier_name": { "type": "string", "minLength": 1, "description": "The carrier delivering the shipment." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InboundShipment.LineItem" }, "minItems": 1, "description": "The products in the shipment. At least one." }, "delivery_note_url": { "type": "string", "description": "Link to the delivery note, once it exists. Read-only." }, "status": { "$ref": "#/components/schemas/InboundShipmentStatus", "description": "Reception progress. Read-only." }, "create_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "When the shipment was created. Read-only." }, "public_appointment_url": { "type": "string", "description": "Link to book or view the delivery slot. Only returned by create and update." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Currency of `unit_landed_cost`. Read-only. Set from the warehouse's valuation currency, or the default currency of the warehouse's country." }, "appointment": { "$ref": "#/components/schemas/InboundShipmentAppointment", "description": "The delivery slot and whether the warehouse approved it. Read-only. Only returned by get and list. See [Delivery appointments](/docs/store-api/inbound-shipments#delivery-appointments)." }, "receive_to_order": { "type": "boolean", "description": "Receive the shipment in cross-dock mode. See [Cross-docking](/docs/store-api/inbound-shipments#cross-docking). Set on create only." } } }, "InboundShipment.LineItem": { "type": "object", "description": "LineItem describes an inbound shipment item, with the product ID, the supplier and the quantity of this product in the inbound shipment. Also included the lot_code of the batch of product and the date of expiration of the batch of product. Also included a boolean which is true if the product is blocked for quality control (corresponds to ProductUnavailabilityReason == PRODUCT_UNAVAILABILITY_REASON_QUALITY_CONTROL)", "required": [ "product", "quantity" ], "properties": { "product": { "type": "string", "pattern": "^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Product ID. Bundles can't be received." }, "supplier_sku": { "type": "string", "description": "The supplier's reference for the product." }, "quantity": { "type": "integer", "format": "int32", "exclusiveMinimum": 0, "description": "Units expected. Must be greater than 0." }, "lot_code": { "type": "string", "maxLength": 20, "description": "Lot code. Required for products with `track_lots`." }, "lot_expiration_date": { "type": "string", "pattern": "\\d{4}-\\d{2}-\\d{2}", "description": "Lot expiry date. Required for products with `track_lot_expiry`." }, "lot_expiration_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "Use `lot_expiration_date` instead." }, "block_for_quality_control": { "type": "boolean", "description": "Receive the units into quality control instead of sellable stock. They appear as `quality_control` in [inventory](/docs/store-api/inventory) until released." }, "unit_landed_cost": { "type": "string", "description": "Cost per unit including freight, duties and handling, as a decimal string. Used for stock valuation. If missing, the product's `value` is used." } } }, "InboundShipmentForm": { "type": "object", "description": "InboundShipmentForm is used to create inbound shipments.", "required": [ "supplier_shipment_id", "supplier_name", "warehouse", "expected_arrival_time", "carrier_name", "line_items" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{13}$", "description": "Your own ID, so retries don't create duplicates. Generated if empty." }, "supplier_shipment_id": { "type": "string", "minLength": 1, "description": "Your or your supplier's reference for the shipment." }, "supplier_name": { "type": "string", "minLength": 1, "description": "Who is sending the goods." }, "warehouse": { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$", "description": "Destination warehouse. Must be one of your warehouses." }, "expected_arrival_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "RFC 3339 UTC, for example `2026-04-02T08:00:00Z`." }, "expected_pallet_count": { "type": "integer", "format": "int32", "deprecated": true, "description": "Use `expected_load.pallet_load` instead." }, "expected_box_count": { "type": "integer", "format": "int32", "deprecated": true, "description": "Use `expected_load.box_load` instead." }, "expected_load": { "$ref": "#/components/schemas/InboundShipmentLoad", "description": "How the goods are packed. Set one of the four load types." }, "carrier_name": { "type": "string", "minLength": 1, "description": "The carrier delivering the shipment." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InboundShipment.LineItem" }, "minItems": 1, "description": "At least one line. Products only." }, "receive_to_order": { "type": "boolean", "description": "Receive in cross-dock mode: orders can reserve the expected quantities before the shipment arrives. Can't be changed later. See [Cross-docking](/docs/store-api/inbound-shipments#cross-docking)." } } }, "InboundShipmentStatus": { "type": "object", "description": "InboundShipmentStatus is used to specify an Inbound shipment's status, with the progress and details.", "properties": { "code": { "type": "string", "description": "One of the [statuses](#statuses)." }, "update_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "When the status last changed." }, "total_expected_count": { "type": "integer", "format": "int32", "description": "Total units declared." }, "total_offloaded_count": { "type": "integer", "format": "int32", "description": "Units received in good condition. Doesn't include damaged units." }, "total_damaged_count": { "type": "integer", "format": "int32", "description": "Units received damaged." }, "comments": { "type": "array", "items": { "type": "string" }, "description": "Notes from warehouse staff, for example about missing or damaged units." }, "line_progresses": { "type": "array", "items": { "$ref": "#/components/schemas/InboundShipmentStatus.LineProgress" }, "description": "Reception details per line." } } }, "InboundShipmentStatus.LineProgress": { "type": "object", "description": "LineProgress describes the progress made for an inbound shipment item.", "properties": { "product": { "type": "string", "pattern": "^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Product ID." }, "expected_count": { "type": "integer", "format": "int32", "description": "Units declared." }, "offloaded_count": { "type": "integer", "format": "int32", "description": "Units received in good condition." }, "damaged_count": { "type": "integer", "format": "int32", "description": "Units received damaged." }, "lot_code": { "type": "string", "maxLength": 20, "description": "Lot the units were received into." }, "lot_expiration_date": { "type": "string", "pattern": "\\d{4}-\\d{2}-\\d{2}", "description": "Lot expiry date, `YYYY-MM-DD`." }, "lot_expiration_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "Use `lot_expiration_date` instead." } } }, "PalletLoad": { "type": "object", "description": "This object represents a pallet load for an inbound shipment.", "properties": { "homogeneous_pallet_count": { "type": "integer", "format": "int32", "description": "Pallets with one product." }, "heterogeneous_pallet_count": { "type": "integer", "format": "int32", "description": "Pallets with several products." }, "heterogeneous_pallet_homogeneous_box_count": { "type": "integer", "format": "int32", "description": "Boxes with one product on mixed pallets." }, "heterogeneous_pallet_heterogeneous_box_count": { "type": "integer", "format": "int32", "description": "Boxes with several products on mixed pallets." } } }, "BoxLoad": { "type": "object", "description": "This object represents a box load (no pallet) for an inbound shipment.", "properties": { "homogeneous_box_count": { "type": "integer", "format": "int32", "description": "Boxes that contain one product." }, "heterogeneous_box_count": { "type": "integer", "format": "int32", "description": "Boxes that contain several products." } } }, "FloorLoadedContainerLoad": { "type": "object", "description": "This object represents a container (floor loaded) load for an inbound shipment.", "required": [ "box_load" ], "properties": { "container_seal_reference": { "type": "string", "maxLength": 60, "description": "The container's seal number." }, "box_load": { "$ref": "#/components/schemas/BoxLoad", "description": "The boxes in the container." } } }, "PalletizedContainerLoad": { "type": "object", "description": "This object represents a container (palletized) load for an inbound shipment.", "required": [ "pallet_load" ], "properties": { "container_seal_reference": { "type": "string", "maxLength": 60, "description": "The container's seal number." }, "pallet_load": { "$ref": "#/components/schemas/PalletLoad", "description": "The pallets in the container." } } }, "InboundShipmentLoad": { "type": "object", "description": "This object describes the inbound shipment load.\n\nSet only one of `box_load`, `pallet_load`, `floor_loaded_container_load`, `palletized_container_load`.\n\nSet exactly one load type.", "properties": { "box_load": { "$ref": "#/components/schemas/BoxLoad", "description": "Boxes, not on pallets." }, "pallet_load": { "$ref": "#/components/schemas/PalletLoad", "description": "Pallets, not in a container." }, "floor_loaded_container_load": { "$ref": "#/components/schemas/FloorLoadedContainerLoad", "description": "A container with loose boxes." }, "palletized_container_load": { "$ref": "#/components/schemas/PalletizedContainerLoad", "description": "A container with pallets." } } }, "InboundShipmentAppointment": { "type": "object", "properties": { "status": { "type": "string", "description": "`PENDING`, `APPROVED`, `REFUSED` or `CANCELLED`. See [Delivery appointments](/docs/store-api/inbound-shipments#delivery-appointments)." }, "time_slot_start_time": { "type": "string", "description": "Start of the requested slot, RFC 3339." }, "time_slot_end_time": { "type": "string", "description": "End of the requested slot, RFC 3339." }, "warehouse_approval_note": { "type": "string", "description": "Instructions for the carrier, added by the warehouse when it approves the slot." }, "update_time": { "type": "string", "description": "When the request was last created, approved, refused or cancelled." } } }, "Inventory": { "type": "object", "description": "Inventory counts of a product in a warehouse.\n\n`available` is what you can sell now. `in_warehouse` includes units reserved\nfor orders, so reserved units are `in_warehouse - available`.", "properties": { "product": { "type": "string", "pattern": "^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Product ID." }, "warehouse": { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$", "description": "Warehouse ID." }, "available": { "type": "integer", "format": "int32", "description": "Units you can sell now: in the warehouse, in good condition and not reserved for an order. Publish this number to your storefront." }, "in_warehouse": { "type": "integer", "format": "int32", "description": "Units in the warehouse in good condition, including units reserved for unshipped orders. Doesn't include damaged, quality control or expired units." }, "damaged": { "type": "integer", "format": "int32", "description": "Damaged units. Can't be sold." }, "quality_control": { "type": "integer", "format": "int32", "description": "Units held for inspection, usually received with `block_for_quality_control`. Can't be sold until released." }, "expired": { "type": "integer", "format": "int32", "description": "Units past their sell-by limit, set by the product's `lot_expiry_threshold_days`. Can't be sold." }, "backordered": { "type": "integer", "format": "int32", "description": "Units ordered that stock couldn't cover." }, "lots": { "type": "array", "items": { "$ref": "#/components/schemas/Inventory.Lot" }, "description": "Counts per lot. Only included when lot tracking is on for your account and the product has `track_lots`. Up to 100 lots per row." } } }, "Inventory.Lot": { "type": "object", "description": "Inventory counts of a lot in a warehouse.", "properties": { "lot_code": { "type": "string", "maxLength": 20, "description": "Lot code from the inbound shipment." }, "lot_expiration_date": { "type": "string", "pattern": "\\d{4}-\\d{2}-\\d{2}", "description": "Lot expiry date." }, "lot_expiration_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "Use `lot_expiration_date` instead." }, "in_warehouse": { "type": "integer", "format": "int32", "description": "Good units in the lot." }, "damaged": { "type": "integer", "format": "int32", "description": "Damaged units in the lot." }, "quality_control": { "type": "integer", "format": "int32", "description": "Units in the lot held for inspection." }, "expired": { "type": "integer", "format": "int32", "description": "Expired units in the lot." } } }, "BundleInventory": { "type": "object", "description": "Inventory counts of a bundle in a warehouse.", "properties": { "bundle": { "type": "string", "pattern": "^[A-Za-z0-9]{4}BU-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Bundle ID." }, "warehouse": { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$", "description": "Warehouse ID." }, "available": { "type": "integer", "format": "int32", "description": "Bundles you can sell now." }, "in_warehouse": { "type": "integer", "format": "int32", "description": "Bundles that could be made from good stock, including reserved units." } } }, "AllocationInventory": { "type": "object", "properties": { "warehouse": { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$", "description": "Warehouse ID." }, "product": { "type": "string", "pattern": "^[A-Za-z0-9]{4}(BU)?-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Product or bundle ID." }, "product_sku": { "type": "string", "maxLength": 40, "description": "Your SKU for the product. Empty for bundles." }, "shop_inventory_location_quantities": { "type": "array", "items": { "$ref": "#/components/schemas/AllocationInventory.ShopInventoryLocationQuantity" }, "description": "One entry per sales channel." }, "remaining_available_quantity": { "type": "integer", "format": "int32", "description": "Available units not allocated to any channel. Can be negative." } } }, "AllocationInventory.ShopInventoryLocationQuantity": { "type": "object", "description": "The shop inventory location quantity represents the available quantity of a product or bundle for a shop.", "properties": { "inventory_location": { "$ref": "#/components/schemas/AllocationInventory.ShopInventoryLocation", "description": "The sales channel." }, "available_quantity": { "type": "integer", "format": "int32", "description": "Units the channel can sell. Can be negative." } } }, "AllocationInventory.ShopInventoryLocation": { "type": "object", "description": "A shop inventory location represents a sales channel that can be linked to an allocation group.", "properties": { "shop": { "type": "string", "pattern": "^[a-z0-9]{1,2}_[A-Za-z0-9]{8}$", "description": "Bigblue shop ID, for example `sh_1a2b3c4d`." }, "inventory_location": { "type": "string", "description": "The shop's own location ID, if the platform has one, such as a Shopify location." } } }, "Order": { "type": "object", "description": "Holds information about an order.\n\nIf the order was edited in the Bigblue app and the prices no longer add up, the\ndifference is returned as `additional_tax` and `shipping_tax` is `\"0\"`.", "properties": { "id": { "type": "string", "pattern": "^([A-Za-z0-9]{12})$", "description": "Bigblue order ID." }, "external_id": { "type": "string", "description": "Your own order reference." }, "store": { "type": "string", "description": "The integration that created the order. Read-only." }, "submit_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "When Bigblue received the order, RFC 3339 UTC. Set by Bigblue." }, "language": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Language for customer notifications, ISO 639-1." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Currency for all amounts on the order, ISO 4217." }, "shipping_address": { "$ref": "#/components/schemas/ShippingAddress", "description": "Delivery address and customer contact details." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/Order.LineItem" }, "minItems": 1, "description": "Items ordered. At least one." }, "shipping_price": { "type": "string", "minLength": 1, "description": "Shipping price paid by the customer." }, "shipping_tax": { "type": "string", "description": "Tax on shipping." }, "additional_tax": { "type": "string", "description": "Tax not tied to a line item or to shipping." }, "additional_discount": { "type": "string", "description": "Order-level discount, in addition to line discounts." }, "total": { "type": "string", "minLength": 1, "description": "Order total, calculated by Bigblue. See [Prices](#prices)." }, "shipping_method": { "type": "string", "description": "Name of the shipping method the customer chose." }, "billing_address": { "$ref": "#/components/schemas/BillingAddress", "description": "Billing address. Defaults to the shipping address." }, "pickup_point": { "$ref": "#/components/schemas/PickupPoint", "description": "Pickup point, if the parcel isn't delivered to the address." }, "status": { "$ref": "#/components/schemas/Order.Status", "description": "Status code and message. Read-only. Not included in the create response." }, "tracking_number": { "type": "string", "description": "Tracking number of the most advanced parcel. Read-only." }, "tracking_url": { "type": "string", "description": "Tracking page for that parcel. Read-only." }, "b2b": { "type": "boolean", "description": "The order is a B2B shipment." }, "b2b_fulfillment_instructions_template": { "type": "string", "maxLength": 32, "description": "B2B instructions template applied to the order." }, "shipped_packages": { "type": "array", "items": { "$ref": "#/components/schemas/OrderPackage" }, "description": "Contents of each packed parcel. Read-only." }, "experience": { "type": "string", "pattern": "^xp_[0-9]{5}$", "description": "The resolved experience of an order. It can either be a \"forced experience\" (provided at the order creation) or a resolved one (based on shop, and other criteria)." }, "external_order_url": { "type": "string", "description": "Link to the order in your system, shown to Bigblue support." }, "customer_order_id": { "type": "string", "maxLength": 20, "description": "Your customer's purchase order (PO) number, passed to the carrier." } } }, "Order.LineItem": { "type": "object", "description": "Order item with the product ID, ordered quantity of the product, and the different prices/discount (unit, tax).\n\n`discount` is the total for the line, not per unit. Amounts are decimal\nstrings, for example `\"24.90\"`.", "required": [ "product", "quantity", "unit_price", "unit_tax" ], "properties": { "product": { "type": "string", "pattern": "^[A-Za-z0-9]{4}(BU)?-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Product or bundle ID." }, "quantity": { "type": "integer", "format": "int32", "exclusiveMinimum": 0, "description": "Units ordered, or bundles for a bundle line. Greater than 0." }, "unit_price": { "type": "string", "minLength": 1, "description": "Price of one unit." }, "unit_tax": { "type": "string", "minLength": 1, "description": "Tax on one unit." }, "discount": { "type": "string", "description": "Total discount for the line, not per unit." }, "lot_code": { "type": "string", "maxLength": 64, "description": "Pick from this lot. Can't be used with `lot_expiration_days_range_rule`." }, "lot_expiration_date": { "type": "string", "pattern": "\\d{4}-\\d{2}-\\d{2}", "description": "Expiry date of the lot set in `lot_code`." }, "lot_expiration_time": { "type": "string", "description": "Use `lot_expiration_date` instead." }, "lot_expiration_days_range_rule": { "$ref": "#/components/schemas/LotExpirationDaysRangeRule", "description": "Pick from a lot whose remaining shelf life is in this range. Can't be used with `lot_code`." } } }, "Order.Status": { "type": "object", "description": "Order status.", "properties": { "code": { "type": "string", "description": "Status code." }, "message": { "type": "string", "description": "Message associated to the status." } } }, "OrderForm": { "type": "object", "description": "Used to create orders.", "required": [ "language", "currency", "shipping_address", "line_items", "shipping_price" ], "properties": { "id": { "type": "string", "pattern": "^([A-Za-z0-9]{12}|)$", "description": "Your own order ID. Generated if empty." }, "external_id": { "type": "string", "description": "Your own order reference. To find the order by it later, use the `external_order` filter on [`ListTrackings`](/docs/store-api/tracking/list-trackings)." }, "language": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 639-1 code for customer notifications." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 code." }, "shipping_address": { "$ref": "#/components/schemas/ShippingAddress", "description": "Delivery address. Needs `line1`, `city` and `country`." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/Order.LineItem" }, "minItems": 1, "description": "At least one line. Products or bundles." }, "shipping_price": { "type": "string", "minLength": 1, "description": "Shipping price. Send `\"0\"` for free shipping." }, "shipping_tax": { "type": "string", "description": "Tax on shipping." }, "additional_tax": { "type": "string", "description": "Tax not tied to a line or to shipping." }, "additional_discount": { "type": "string", "description": "Order-level discount." }, "shipping_method": { "type": "string", "description": "Name of the shipping method the customer chose. Shown in the app." }, "billing_address": { "$ref": "#/components/schemas/BillingAddress", "description": "Defaults to the shipping address." }, "pickup_point": { "$ref": "#/components/schemas/PickupPoint", "description": "Deliver to a pickup point. Needs `id`, `country` and `carrier_service`." }, "b2b": { "type": "boolean", "description": "Mark the order as a B2B shipment." }, "b2b_fulfillment_instructions_template": { "type": "string", "maxLength": 32, "description": "B2B instructions template set up in the Bigblue app. Requires `b2b: true`." }, "experience": { "type": "string", "pattern": "^xp_[0-9]{5}$", "description": "The optional ID of the experience of the order. If not provided, it will be resolved based on shop and other criteria." }, "auto_fulfill_schedule_hold": { "type": "boolean", "description": "Hold the order until you release it. Overrides `auto_fulfill_schedule_time`." }, "auto_fulfill_schedule_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "Don't fulfill before this time, RFC 3339 UTC." }, "auto_fulfill_reservation_priority": { "$ref": "#/components/schemas/FulfillmentPriority", "description": "`FULFILLMENT_PRIORITY_LOW`, `FULFILLMENT_PRIORITY_NORMAL` or `FULFILLMENT_PRIORITY_HIGH`." }, "auto_fulfill_warehouse": { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$", "description": "Ship from this warehouse instead of the integration's primary warehouse." }, "external_order_url": { "type": "string", "description": "Link to the order in your system." }, "customer_order_id": { "type": "string", "maxLength": 20, "description": "Your customer's purchase order (PO) number. Up to 20 ASCII characters. Passed to the carrier with the shipment." } } }, "ShippingAddress": { "type": "object", "description": "Information on the customer and shipping address.\n\nValues longer than the limits are rejected, not shortened.", "required": [ "line1", "city", "country" ], "properties": { "first_name": { "type": "string", "maxLength": 38, "description": "Customer's first name." }, "last_name": { "type": "string", "maxLength": 38, "description": "Customer's last name." }, "company": { "type": "string", "maxLength": 38, "description": "Company name." }, "phone": { "type": "string", "maxLength": 32, "description": "Phone number. Some carriers need it for delivery updates." }, "email": { "type": "string", "maxLength": 128, "description": "Email for shipping notifications." }, "line1": { "type": "string", "minLength": 1, "maxLength": 38, "description": "Street address." }, "line2": { "type": "string", "maxLength": 38, "description": "Address line 2." }, "line3": { "type": "string", "maxLength": 38, "description": "Address line 3." }, "line4": { "type": "string", "maxLength": 38, "description": "Address line 4." }, "city": { "type": "string", "minLength": 1, "maxLength": 38, "description": "City." }, "postal": { "type": "string", "maxLength": 12, "description": "Postal code." }, "state": { "type": "string", "maxLength": 38, "description": "State or province." }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2." } } }, "BillingAddress": { "type": "object", "description": "BillingAddress is the data structure for an Order billing address.\n\nAll fields are optional. Leave it out to use the shipping address.", "properties": { "first_name": { "type": "string", "maxLength": 38 }, "last_name": { "type": "string", "maxLength": 38 }, "email": { "type": "string", "maxLength": 128 }, "company": { "type": "string", "maxLength": 38 }, "line1": { "type": "string", "maxLength": 38 }, "line2": { "type": "string", "maxLength": 38 }, "line3": { "type": "string", "maxLength": 38 }, "line4": { "type": "string", "maxLength": 38 }, "city": { "type": "string", "maxLength": 38 }, "postal": { "type": "string", "maxLength": 12 }, "state": { "type": "string", "maxLength": 38 }, "country": { "type": "string", "maxLength": 2 } } }, "PickupPoint": { "type": "object", "description": "PickupPoint can be used to specify the pickup point in an Order.", "required": [ "id", "country", "carrier_service" ], "properties": { "id": { "type": "string", "minLength": 2, "maxLength": 12, "description": "The carrier's pickup point ID." }, "display_name": { "type": "string", "maxLength": 64, "description": "Name shown to the customer." }, "postal": { "type": "string", "maxLength": 12, "description": "Postal code." }, "state": { "type": "string", "maxLength": 38, "description": "State or province." }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2." }, "carrier_service": { "type": "string", "minLength": 5, "maxLength": 32, "description": "Bigblue carrier service for the pickup point. If it doesn't match the point, fulfillment fails." } } }, "OrderPackage": { "type": "object", "description": "OrderPackage specifies the properties and content of a package.", "properties": { "id": { "type": "string", "description": "Package ID." }, "tracking_number": { "type": "string", "description": "Tracking number." }, "weight": { "type": "integer", "format": "int32", "description": "Weight in grams." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderPackage.Item" }, "description": "Contents." } } }, "OrderPackage.Item": { "type": "object", "description": "Ordered items in the package.", "properties": { "product": { "type": "string", "pattern": "^[A-Za-z0-9]{4}(BU)?-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Product ID." }, "quantity": { "type": "integer", "format": "int32", "exclusiveMinimum": 0, "description": "Units in the package." }, "lot_code": { "type": "string", "maxLength": 64, "description": "Lot the units came from." }, "lot_expiration_date": { "type": "string", "pattern": "\\d{4}-\\d{2}-\\d{2}", "description": "Lot expiry date, `YYYY-MM-DD`." }, "lot_expiration_time": { "type": "string", "description": "Use `lot_expiration_date` instead." } } }, "LotExpirationDaysRangeRule": { "type": "object", "description": "Lot selection rule to target a lot with constraints on the expiration date.", "properties": { "minimum_days_to_expiration": { "type": "integer", "format": "int64", "description": "Minimum days until the lot expires. `0` means no minimum." }, "maximum_days_to_expiration": { "type": "integer", "format": "int64", "description": "Maximum days until the lot expires. `0` means no maximum." } } }, "ExternalOrderId": { "type": "object", "required": [ "store", "id" ], "properties": { "store": { "type": "string", "pattern": "^[a-z0-9]{1,2}_[A-Za-z0-9]{8}$", "description": "Bigblue shop ID, for example `sh_1a2b3c4d`." }, "id": { "type": "string", "minLength": 1, "description": "The order's `external_id` in that shop." } } }, "FulfillmentPriority": { "type": "string", "enum": [ "FULFILLMENT_PRIORITY_UNSPECIFIED", "FULFILLMENT_PRIORITY_LOW", "FULFILLMENT_PRIORITY_NORMAL", "FULFILLMENT_PRIORITY_HIGH" ], "description": "The fulfillment priority. Not using the bigblue.common.Priority enum because:\n - Setting priority to the default value (0) in bigblue.common.Priority\n means PRIORITY_LOW, which does not allow representing an \"unspecified\" state.\n - Here, PRIORITY_UNSPECIFIED (0) explicitly indicates that no priority was\n assigned. This enables distinguishing between an unset priority and a low priority assignment." }, "Product": { "type": "object", "description": "Product holds information on a product.", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Bigblue product ID, starting with your tenant code. Example: `BGBL-ESPSRT-SMAL`. Can't be changed." }, "sku": { "type": "string", "maxLength": 40, "description": "Your own reference. Not used for lookups." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Name shown in the Bigblue app and on packing documents." }, "description": { "type": "string", "maxLength": 1280, "description": "Internal description. Not printed on labels." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOption" }, "description": "Variant attributes, such as size or color." }, "weight": { "type": "integer", "format": "int32", "description": "Weight in grams. Read-only. Measured by the warehouse when the product is first received." }, "width": { "type": "integer", "format": "int32", "description": "Width in millimeters. Read-only. Measured by the warehouse." }, "height": { "type": "integer", "format": "int32", "description": "Height in millimeters. Read-only. Measured by the warehouse." }, "depth": { "type": "integer", "format": "int32", "description": "Depth in millimeters. Read-only. Measured by the warehouse." }, "barcode": { "type": "string", "pattern": "^([0-9]{12,13}|)$", "description": "EAN-13 or UPC-A barcode. Must match the barcode on the item." }, "value": { "$ref": "#/components/schemas/Value", "description": "Declared value of one unit, used for customs and stock valuation." }, "tariff_number": { "type": "string", "pattern": "^[0-9.]{6,16}$", "description": "HS code, for example `6109.10`." }, "origin_country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Country of manufacture, ISO 3166-1 alpha-2." }, "customs_description": { "type": "string", "description": "Description of the goods for customs documents." }, "name_translations": { "type": "array", "items": { "$ref": "#/components/schemas/ProductNameTranslation" }, "description": "Product names in other languages, used on customer documents." }, "track_lots": { "type": "boolean", "description": "Store the product in lots. Inbound shipment lines for it then need a lot code, and inventory is reported per lot." }, "track_lot_expiry": { "type": "boolean", "description": "Lots have an expiry date, which inbound shipment lines must include. Requires `track_lots`." }, "lot_expiry_threshold_days": { "type": "integer", "format": "int32", "description": "Number of days before the expiry date when a lot can no longer be sold. A negative value lets the lot be sold for that many days after expiry. Requires `track_lot_expiry`." }, "non_returnable": { "type": "boolean", "description": "The product can't be returned, for example personalized items." }, "foldable": { "type": "boolean", "description": "The product can be folded once along its longest side, so it fits a smaller box." }, "already_packaged": { "type": "boolean", "description": "The product ships as is, without extra packaging." } } }, "ProductForm": { "type": "object", "description": "ProductForm is used to create a Product.", "required": [ "id", "name", "value", "tariff_number", "origin_country" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Bigblue product ID. Must start with your tenant code." }, "sku": { "type": "string", "maxLength": 40, "description": "Your own reference." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Product name." }, "description": { "type": "string", "maxLength": 1280, "description": "Internal description." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOption" }, "description": "Variant attributes." }, "barcode": { "type": "string", "pattern": "^([0-9]{12,13}|)$", "description": "EAN-13 or UPC-A barcode. Can't be empty." }, "value": { "$ref": "#/components/schemas/Value", "description": "Declared value, for example `{ \"amount\": \"24.90\", \"currency\": \"EUR\" }`." }, "tariff_number": { "type": "string", "pattern": "^[0-9.]{6,16}$", "description": "HS code." }, "origin_country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Country of manufacture." }, "customs_description": { "type": "string", "maxLength": 64, "description": "Description for customs documents." }, "name_translations": { "type": "array", "items": { "$ref": "#/components/schemas/ProductNameTranslation" }, "description": "Names in other languages." }, "track_lots": { "type": "boolean", "description": "Store the product in lots. Can only be set here." }, "track_lot_expiry": { "type": "boolean", "description": "Lots have an expiry date. Requires `track_lots`." }, "lot_expiry_threshold_days": { "type": "integer", "format": "int32", "description": "Days before expiry when a lot can no longer be sold. Can be negative." }, "non_returnable": { "type": "boolean", "description": "The product can't be returned." }, "foldable": { "type": "boolean", "description": "The product can be folded once." }, "already_packaged": { "type": "boolean", "description": "The product ships without extra packaging." } } }, "ProductOption": { "type": "object", "description": "A variant option representing a specificity of a product such as its size or color.", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Attribute name, for example `Size`." }, "value": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Attribute value, for example `Small`." } } }, "ProductNameTranslation": { "type": "object", "description": "Name translations for a Product.", "required": [ "language" ], "properties": { "language": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 639-1 code. Stored in lowercase." }, "name": { "type": "string", "maxLength": 64, "description": "Product name in that language." } } }, "Value": { "type": "object", "description": "Represents a value with the amount and the currency.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "minLength": 1, "description": "Decimal amount as a string, for example `\"24.90\"`. See [Money](/docs/store-api/conventions#money)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 code, for example `EUR`." } } }, "Bundle": { "type": "object", "description": "Bundle represents a \"virtual\" product that hold multiple products.", "required": [ "id", "display_name", "components" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{4}BU-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Bigblue bundle ID: your tenant code, `BU`, then two SKU parts. Example: `BGBLBU-KITSTA-2024`. Can't be changed." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Bundle name, shown in the app and on packing documents." }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/BundleComponent" }, "minItems": 1, "maxItems": 20, "description": "The products in the bundle. 1 to 20 items." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOption" }, "description": "Variant attributes of the bundle." } } }, "BundleComponent": { "type": "object", "description": "Holds a product ID and its associated quantity.", "required": [ "product", "quantity" ], "properties": { "product": { "type": "string", "pattern": "^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "A product ID. Bundles can't contain other bundles." }, "quantity": { "type": "integer", "format": "int32", "exclusiveMinimum": 0, "description": "Units of the product in one bundle. Must be greater than 0." } } }, "Return": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{12}RT[A-Za-z0-9]{2}$", "description": "Return ID: the order ID, `RT`, then two characters. Example: `BGBL0K3M9XQ2RT01`." }, "store": { "type": "string", "minLength": 10, "maxLength": 11, "description": "The sales channel." }, "external_id": { "type": "string", "maxLength": 64, "description": "Your own reference." }, "warehouse": { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$", "description": "The warehouse receiving the return." }, "order": { "type": "string", "pattern": "^[A-Za-z0-9]{12}$", "description": "The order the units came from." }, "fulfillment": { "type": "string", "description": "The fulfillment the units originally shipped in." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnLineItem" }, "minItems": 1, "description": "Units being returned. At least one line." }, "create_time": { "type": "string", "description": "When the return was created." }, "update_time": { "type": "string", "description": "When it last changed." }, "return_time": { "type": "string", "description": "When the warehouse received it." }, "status": { "$ref": "#/components/schemas/ReturnStatus", "description": "Parcel status." }, "label_url": { "type": "string", "description": "Return label for the customer, if Bigblue created one." }, "tracking_number": { "type": "string", "description": "Tracking number of the return parcel." }, "carrier_service": { "type": "string", "description": "Carrier service of the return parcel." }, "label_generation_support": { "$ref": "#/components/schemas/Return.LabelGenerationSupport", "description": "`SUPPORTED` or `UNSUPPORTED`: whether Bigblue can create a return label for this route." }, "utm_medium": { "type": "string", "description": "How the customer reached the returns page, for example `email` or `qr_code`." }, "source": { "$ref": "#/components/schemas/ReturnSource", "description": "Who created the return." }, "origin": { "$ref": "#/components/schemas/ReturnOrigin", "description": "Where the return comes from." }, "refund_method": { "$ref": "#/components/schemas/ReturnRefundMethod", "description": "How the customer chose to be refunded." }, "gift_card": { "$ref": "#/components/schemas/ReturnGiftCard", "description": "Store credit issued, for store credit refunds." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Currency of the amounts on the return." }, "refund_fee": { "type": "string", "description": "Amount taken off the refund, usually the label fee." }, "exchange": { "$ref": "#/components/schemas/ReturnExchange", "description": "Replacement items, for exchanges." }, "resolution_status": { "$ref": "#/components/schemas/ReturnResolutionStatus", "description": "Refund status." }, "resolution_closed_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "When the resolution was closed." }, "manual_resolution": { "$ref": "#/components/schemas/ReturnManualResolution", "description": "Set when you close the return yourself." } } }, "Return.LabelGenerationSupport": { "type": "string", "enum": [ "SUPPORTED", "UNSUPPORTED" ] }, "ReturnForm": { "type": "object", "required": [ "warehouse", "order", "line_items" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{12}RT[A-Za-z0-9]{2}$", "description": "Ignored. Bigblue generates the ID." }, "external_id": { "type": "string", "maxLength": 64, "description": "Your own reference." }, "warehouse": { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$", "description": "The warehouse to return the units to." }, "order": { "type": "string", "pattern": "^[A-Za-z0-9]{12}$", "description": "The order the units came from." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnLineItem" }, "minItems": 1, "description": "Units being returned. At least one line." }, "requested_refund_method": { "$ref": "#/components/schemas/ReturnRefundMethod", "description": "How the customer wants to be refunded. The default, `RETURN_REFUND_METHOD_UNSPECIFIED`, means you refund the customer yourself." }, "tracking_number": { "type": "string", "description": "Ignored on create." }, "manual_resolution": { "$ref": "#/components/schemas/ReturnManualResolution", "description": "Ignored on create. Use [`UpdateReturn`](/docs/store-api/returns/update)." }, "resolution_status": { "$ref": "#/components/schemas/ReturnResolutionStatus", "description": "Ignored on create. Use [`UpdateReturn`](/docs/store-api/returns/update)." } } }, "ReturnLineItem": { "type": "object", "required": [ "product", "expected_quantity" ], "properties": { "id": { "type": "string", "maxLength": 64, "description": "Your own line ID. Must be unique in the return." }, "product": { "type": "string", "pattern": "^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Product ID. Bundles can't be returned as a whole." }, "expected_quantity": { "type": "integer", "format": "int32", "exclusiveMinimum": 0, "description": "Units the customer is sending. Greater than 0." }, "received_quantity": { "type": "integer", "format": "int32", "description": "Units the warehouse received, including damaged units." }, "damaged_quantity": { "type": "integer", "format": "int32", "description": "Received units that are damaged." }, "return_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnReason" }, "description": "One reason per unit when the customer gave them. There may be fewer if you or the warehouse created the return." }, "quality_controls": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnQualityControl" }, "description": "One inspection result per unit, from the warehouse." } } }, "ReturnManualResolution": { "type": "object", "properties": { "refund_method": { "$ref": "#/components/schemas/ReturnRefundMethod", "description": "How you refunded the customer." }, "note": { "type": "string", "description": "A note about the resolution." } } }, "ReturnReason": { "type": "object", "description": "feedback given by the customer about a returned item", "properties": { "type": { "$ref": "#/components/schemas/ReturnReasonType", "description": "Main reason." }, "comment": { "type": "string", "maxLength": 500, "description": "The customer's comment." } } }, "ReturnQualityControl": { "type": "object", "properties": { "damaged_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnDamagedReason" }, "description": "What's wrong with the unit." }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnQualityControlImage" }, "description": "Inspection photos. Each is `{ \"url\": \"https://...\" }`." }, "serial_number": { "$ref": "#/components/schemas/ReturnQualityControl.SerialNumber", "description": "Serial number of the unit, if recorded: `{ \"type\": \"RETURN_SERIAL_NUMBER_TYPE_IMEI\", \"value\": \"...\" }`." } } }, "ReturnQualityControl.SerialNumber": { "type": "object", "required": [ "value" ], "properties": { "type": { "$ref": "#/components/schemas/ReturnSerialNumberType" }, "value": { "type": "string", "minLength": 1 } } }, "ReturnQualityControlImage": { "type": "object", "properties": { "url": { "type": "string" } } }, "ReturnOrigin": { "type": "object", "properties": { "postal": { "type": "string", "maxLength": 12, "description": "Postal code." }, "state": { "type": "string", "maxLength": 38, "description": "State or province." }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2." } } }, "ReturnGiftCard": { "type": "object", "description": "alternative payment method that consists of the buyer entering a code at checkout to get a store credit", "properties": { "store_gift_card_id": { "type": "string", "description": "Gift card ID in your shop." }, "initial_value": { "type": "string", "description": "Credit amount." }, "note": { "type": "string", "description": "Description of the gift card." }, "code_last_characters": { "type": "string", "pattern": "^[A-Za-z0-9]{4}$", "description": "Last four characters of the code." }, "create_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "When the gift card was created." } } }, "ReturnExchange": { "type": "object", "properties": { "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnExchangeLineItem" }, "minItems": 1, "description": "Replacement items. At least one." }, "shipping_price": { "type": "string", "description": "Shipping for the replacement items. Empty until the customer completes checkout." }, "to_refund_amount": { "type": "string", "description": "Amount still owed to the customer: returned items minus replacement items, shipping and `refund_fee`. Empty until checkout is complete." } } }, "ReturnExchangeLineItem": { "type": "object", "description": "ExchangeLineItem holds information about an item which will be bought in exchange for some returned items.", "properties": { "product": { "type": "string", "pattern": "^[A-Za-z0-9]{4}(BU)?-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Bigblue product or bundle. Empty if the shop product isn't linked to Bigblue." }, "product_id": { "type": "string", "minLength": 1, "description": "Product ID in your shop." }, "variant_id": { "type": "string", "description": "Variant ID in your shop, if any." }, "product_title": { "type": "string", "minLength": 1, "description": "Product title." }, "quantity": { "type": "integer", "format": "int64", "exclusiveMinimum": 0, "description": "Units. Greater than 0." }, "price": { "type": "string", "description": "Line price after discounts. Empty until checkout is complete." } } }, "ReturnStatus": { "type": "string", "enum": [ "RETURN_STATUS_UNSPECIFIED", "RETURN_STATUS_CREATED", "RETURN_STATUS_TRANSMITTED", "RETURN_STATUS_SHIPPED", "RETURN_STATUS_RETURNED", "RETURN_STATUS_EXCEPTION", "RETURN_STATUS_CANCELLED" ] }, "ReturnReasonType": { "type": "string", "enum": [ "RETURN_REASON_TYPE_UNSPECIFIED", "RETURN_REASON_TYPE_ITEM_TOO_BIG", "RETURN_REASON_TYPE_ITEM_TOO_SMALL", "RETURN_REASON_TYPE_WRONG_DESCRIPTION", "RETURN_REASON_TYPE_ITEM_DISLIKED", "RETURN_REASON_TYPE_DAMAGED_ITEM", "RETURN_REASON_TYPE_WRONG_ITEM_RECEIVED", "RETURN_REASON_TYPE_OTHER" ], "description": "possible return reason types\n\n- `RETURN_REASON_TYPE_ITEM_TOO_BIG`: the item is bigger than what the customer expected\n- `RETURN_REASON_TYPE_ITEM_TOO_SMALL`: the item is smaller than what the customer expected\n- `RETURN_REASON_TYPE_WRONG_DESCRIPTION`: the item is different from its description on the e-shop\n- `RETURN_REASON_TYPE_ITEM_DISLIKED`: the customer doesn't like the item they received\n- `RETURN_REASON_TYPE_DAMAGED_ITEM`: the item received is damaged or defective\n- `RETURN_REASON_TYPE_WRONG_ITEM_RECEIVED`: the customer received an item different from what was ordered\n- `RETURN_REASON_TYPE_OTHER`: any other reason different from the ones listed above" }, "ReturnDamagedReason": { "type": "string", "enum": [ "RETURN_DAMAGED_REASON_UNSPECIFIED", "RETURN_DAMAGED_REASON_CRUMPLED_PRODUCT", "RETURN_DAMAGED_REASON_DAMAGED_PACKAGING", "RETURN_DAMAGED_REASON_DAMAGED_PRODUCT", "RETURN_DAMAGED_REASON_MISSING_OR_UNREADABLE_BARCODE", "RETURN_DAMAGED_REASON_DIRTY_PRODUCT", "RETURN_DAMAGED_REASON_SERIAL_NUMBER_MISMATCH" ], "description": "possible damaged reasons\n\n- `RETURN_DAMAGED_REASON_CRUMPLED_PRODUCT`: the product is crumpled\n- `RETURN_DAMAGED_REASON_DAMAGED_PACKAGING`: the product packaging is damaged\n- `RETURN_DAMAGED_REASON_DAMAGED_PRODUCT`: the product itself is damaged\n- `RETURN_DAMAGED_REASON_MISSING_OR_UNREADABLE_BARCODE`: the barcode is missing or unreadable\n- `RETURN_DAMAGED_REASON_DIRTY_PRODUCT`: the product is dirty\n- `RETURN_DAMAGED_REASON_SERIAL_NUMBER_MISMATCH`: the serial number of the product is unexpected or missing" }, "ReturnSerialNumberType": { "type": "string", "enum": [ "RETURN_SERIAL_NUMBER_TYPE_UNSPECIFIED", "RETURN_SERIAL_NUMBER_TYPE_IMEI" ], "description": "Possible types of serial numbers\n\n- `RETURN_SERIAL_NUMBER_TYPE_IMEI`: IMEI (15 digits mobile equipment identifier)." }, "ReturnSource": { "type": "string", "enum": [ "RETURN_SOURCE_UNSPECIFIED", "RETURN_SOURCE_CUSTOMER", "RETURN_SOURCE_MERCHANT", "RETURN_SOURCE_WAREHOUSE", "RETURN_SOURCE_INTEGRATION", "RETURN_SOURCE_CARRIER" ], "description": "\n- `RETURN_SOURCE_CUSTOMER`: return created by customer\n- `RETURN_SOURCE_MERCHANT`: return created by merchant\n- `RETURN_SOURCE_WAREHOUSE`: \"unannounced return\". In most case it corresponds to carrier return but it can be customer returned which has not been created in the return portal these are return sent by the warehouse for which we don't have an entry on our side\n- `RETURN_SOURCE_INTEGRATION`: return created by shopify return API from a third party portal.\n- `RETURN_SOURCE_CARRIER`: carrier return created when the initial fulfillment is returned to the warehouse." }, "ReturnRefundMethod": { "type": "string", "enum": [ "RETURN_REFUND_METHOD_UNSPECIFIED", "RETURN_REFUND_METHOD_STORE_CREDIT", "RETURN_REFUND_METHOD_EXCHANGE", "RETURN_REFUND_METHOD_MANUAL_OTHER" ], "description": "possible return refund methods\n\n- `RETURN_REFUND_METHOD_UNSPECIFIED`: it corresponds to \"manual refund\", the merchant refunds the customer directly with the mechanism they wants\n- `RETURN_REFUND_METHOD_STORE_CREDIT`: a store credit is granted to the customer equivalent to the value of their return\n- `RETURN_REFUND_METHOD_EXCHANGE`: The customer can order new items in exchange of return items.\n- `RETURN_REFUND_METHOD_MANUAL_OTHER`: The merchant manually close the return and declare the refund method used as \"other\"." }, "ReturnResolutionStatus": { "type": "string", "enum": [ "RETURN_RESOLUTION_STATUS_UNSPECIFIED", "RETURN_RESOLUTION_STATUS_OPEN", "RETURN_RESOLUTION_STATUS_ACTION_REQUIRED", "RETURN_RESOLUTION_STATUS_CLOSED" ] }, "OrderTicket": { "type": "object", "description": "Holds information about helpdesk items associated to an order.", "properties": { "id": { "type": "string", "pattern": "[A-Za-z0-9]{27}", "description": "Ticket ID." }, "reference": { "type": "string", "pattern": "^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "The order ID." }, "subject": { "type": "string", "minLength": 1, "description": "Ticket title, for example \"Items are missing\"." }, "status": { "$ref": "#/components/schemas/OrderTicketStatus", "description": "Ticket status." }, "create_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "When the ticket was opened." }, "update_time": { "type": "string", "pattern": "\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z", "description": "When the ticket last changed." } } }, "OrderTicketStatus": { "type": "string", "enum": [ "ORDER_TICKET_STATUS_INVALID", "ORDER_TICKET_STATUS_OPEN", "ORDER_TICKET_STATUS_AWAITING_YOUR_REPLY", "ORDER_TICKET_STATUS_CLOSED" ], "description": "The status of a ticket." }, "Tracking": { "type": "object", "properties": { "tracking_number": { "type": "string", "description": "The tracking number printed on the label. Stays the same if the carrier issues a new number later." }, "carrier_service": { "type": "string", "description": "Bigblue carrier service ID." }, "tracking_url": { "type": "string", "description": "Tracking page for the customer." }, "update_time": { "type": "string", "description": "When the tracking last changed." }, "status": { "$ref": "#/components/schemas/Tracking.Status", "description": "Current status." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingEvent" }, "description": "All events, newest first." } } }, "Tracking.Status": { "type": "object", "properties": { "code": { "type": "string", "description": "One of the [status codes](#status-codes)." }, "message": { "type": "string", "description": "Description of the latest event. Don't use it in your logic." } } }, "TrackingEvent": { "type": "object", "properties": { "status_code": { "type": "string", "description": "Status code for this event." }, "message": { "type": "string", "description": "The carrier's description of the event." }, "timestamp": { "type": "string", "description": "When the event happened, RFC 3339 UTC. If the carrier didn't send a time, this is when Bigblue recorded the event." } } }, "CreateProductRequest": { "type": "object", "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/ProductForm", "description": "The product to create." } } }, "CreateProductResponse": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product", "description": "The new product. Dimensions are missing until the warehouse measures it." } } }, "UpdateProductRequest": { "type": "object", "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/ProductForm", "description": "The full product. `id` identifies the product and can't change. `name`, `barcode` and `value` are required." } } }, "UpdateProductResponse": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product", "description": "The updated product." } } }, "GetProductRequest": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Bigblue product ID." } } }, "GetProductResponse": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product", "description": "The product, including dimensions once measured." } } }, "ListProductsRequest": { "type": "object", "properties": { "page_token": { "type": "string", "description": "The `next_page_token` from the previous response. Leave empty for the first page." }, "page_size": { "type": "integer", "format": "int32", "description": "Products per page." } } }, "ListProductsResponse": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" }, "description": "The products on this page." }, "next_page_token": { "type": "string", "description": "Token for the next page. Missing on the last page." } } }, "DeleteProductRequest": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Bigblue product ID." } } }, "DeleteProductResponse": { "type": "object", "properties": {} }, "CreateBundleRequest": { "type": "object", "required": [ "bundle" ], "properties": { "bundle": { "$ref": "#/components/schemas/Bundle", "description": "The bundle to create." } } }, "CreateBundleResponse": { "type": "object", "properties": { "bundle": { "$ref": "#/components/schemas/Bundle", "description": "The new bundle." } } }, "UpdateBundleRequest": { "type": "object", "required": [ "bundle" ], "properties": { "bundle": { "$ref": "#/components/schemas/Bundle", "description": "The full bundle. `id` identifies the bundle and can't change." } } }, "UpdateBundleResponse": { "type": "object", "properties": { "bundle": { "$ref": "#/components/schemas/Bundle", "description": "The updated bundle." } } }, "GetBundleRequest": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{4}BU-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Bigblue bundle ID." } } }, "GetBundleResponse": { "type": "object", "properties": { "bundle": { "$ref": "#/components/schemas/Bundle", "description": "The bundle and its components." } } }, "ListBundlesRequest": { "type": "object", "properties": { "page_token": { "type": "string", "description": "The `next_page_token` from the previous response." }, "page_size": { "type": "integer", "format": "int32", "description": "Bundles per page." } } }, "ListBundlesResponse": { "type": "object", "properties": { "bundles": { "type": "array", "items": { "$ref": "#/components/schemas/Bundle" }, "description": "The bundles on this page." }, "next_page_token": { "type": "string", "description": "Token for the next page. Missing on the last page." } } }, "DeleteBundleRequest": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{4}BU-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$", "description": "Bigblue bundle ID." } } }, "DeleteBundleResponse": { "type": "object", "properties": {} }, "CreateInboundShipmentRequest": { "type": "object", "required": [ "inbound_shipment" ], "properties": { "inbound_shipment": { "$ref": "#/components/schemas/InboundShipmentForm", "description": "The shipment to create." }, "finalize": { "type": "boolean", "description": "Send the shipment to the warehouse right away." } } }, "CreateInboundShipmentResponse": { "type": "object", "properties": { "inbound_shipment": { "$ref": "#/components/schemas/InboundShipment", "description": "The new shipment, with its `id`, `currency`, `status` and `public_appointment_url`. Doesn't include `appointment`." } } }, "DeleteInboundShipmentRequest": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{13}$", "description": "Bigblue inbound shipment ID." } } }, "UpdateInboundShipmentRequest": { "type": "object", "required": [ "update_mask" ], "properties": { "inbound_shipment": { "$ref": "#/components/schemas/InboundShipmentForm", "description": "The shipment, with `id` set. Only fields in `update_mask` are read." }, "update_mask": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true, "description": "Fields to update. At least one, with no duplicates." } } }, "UpdateInboundShipmentResponse": { "type": "object", "properties": { "inbound_shipment": { "$ref": "#/components/schemas/InboundShipment", "description": "The updated shipment, with `public_appointment_url`. Doesn't include `appointment`." } } }, "DeleteInboundShipmentResponse": { "type": "object", "properties": {} }, "GetInboundShipmentRequest": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{13}$", "description": "Bigblue inbound shipment ID." } } }, "GetInboundShipmentResponse": { "type": "object", "properties": { "inbound_shipment": { "$ref": "#/components/schemas/InboundShipment", "description": "The shipment with its status and line progress." } } }, "ListInboundShipmentsRequest": { "type": "object", "description": "Filters are combined with AND; values inside a repeated filter are combined with OR. An unset or empty filter is ignored.", "properties": { "warehouses": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "uniqueItems": true, "description": "Only return shipments to these warehouses." }, "line_item_products": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "uniqueItems": true, "description": "Only return shipments containing at least one of these products." }, "status_codes": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "uniqueItems": true, "description": "Only return shipments whose `status.code` is one of these values: `DRAFT`, `PENDING`, `TRANSMITTED`, `ARRIVED`, `OFFLOADING`, `COMPLETE` or `ARCHIVED`." }, "supplier_name": { "type": "string", "maxLength": 255, "description": "Only return shipments whose supplier name contains this value. Case-insensitive." }, "supplier_shipment_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Only return shipments with exactly this supplier shipment ID." }, "page_token": { "type": "string", "description": "The `next_page_token` from the previous response." }, "page_size": { "type": "integer", "format": "int32", "description": "Shipments per page." } } }, "ListInboundShipmentsResponse": { "type": "object", "properties": { "inbound_shipments": { "type": "array", "items": { "$ref": "#/components/schemas/InboundShipment" }, "description": "The shipments on this page." }, "next_page_token": { "type": "string", "description": "Token for the next page. Missing on the last page." } } }, "ListInventoriesRequest": { "type": "object", "properties": { "warehouse": { "type": "string", "pattern": "^([A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}|)$", "description": "Only return this warehouse." }, "product": { "type": "string", "pattern": "^([A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}|)$", "description": "Only return this product. Bundle IDs aren't accepted." }, "page_token": { "type": "string", "description": "The `next_page_token` from the previous response." }, "page_size": { "type": "integer", "format": "int32", "maximum": 1000, "description": "Rows per page." } } }, "ListBundleInventoriesRequest": { "type": "object", "properties": { "warehouse": { "type": "string", "pattern": "^([A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}|)$", "description": "Only return this warehouse." }, "page_token": { "type": "string", "description": "The `next_page_token` from the previous response." }, "page_size": { "type": "integer", "format": "int32", "description": "Rows per page." } } }, "ListBundleInventoriesResponse": { "type": "object", "properties": { "bundle_inventories": { "type": "array", "items": { "$ref": "#/components/schemas/BundleInventory" }, "description": "One row per bundle and warehouse." }, "next_page_token": { "type": "string", "description": "Token for the next page. Missing on the last page." } } }, "ListInventoriesResponse": { "type": "object", "properties": { "inventories": { "type": "array", "items": { "$ref": "#/components/schemas/Inventory" }, "description": "One row per product and warehouse." }, "next_page_token": { "type": "string", "description": "Token for the next page. Missing on the last page." } } }, "CreateOrderRequest": { "type": "object", "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/OrderForm", "description": "The order to create." }, "force_merge_line_items": { "type": "boolean", "description": "Merge lines with the same product or bundle into one line." } } }, "CreateOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order", "description": "The new order with `id`, `store` and `submit_time`. Doesn't include `status`, `shipped_packages` or tracking." } } }, "UpdateOrderRequest": { "type": "object", "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/OrderForm", "description": "The full order, with `id` set." } } }, "UpdateOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order", "description": "The updated order, with tracking if a parcel exists." } } }, "CancelOrderRequest": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^([A-Za-z0-9]{12}|)$", "description": "Bigblue order ID." }, "reason": { "type": "string", "description": "Why the order was cancelled. Shown in the Bigblue app." } } }, "CancelOrderResponse": { "type": "object", "properties": {} }, "GetOrderRequest": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{12}$", "description": "Bigblue order ID." } } }, "GetOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order", "description": "The order with its status, packages and tracking." } } }, "ListOrdersRequest": { "type": "object", "properties": { "via_api": { "type": "boolean", "description": "Only return orders created by the integration of the calling API key." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Only return orders shipping to these countries. Two-letter codes." }, "date_range": { "$ref": "#/components/schemas/DateRange", "description": "Only return orders submitted in this period." }, "page_token": { "type": "string", "description": "The `next_page_token` from the previous response." }, "page_size": { "type": "integer", "format": "int32", "description": "Orders per page." } } }, "ListOrdersResponse": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "description": "The orders on this page." }, "next_page_token": { "type": "string", "description": "Token for the next page. Missing on the last page." } } }, "ListOrderTicketsRequest": { "type": "object", "required": [ "reference" ], "properties": { "reference": { "type": "string", "minLength": 1, "description": "The 12-character Bigblue order ID." }, "page_token": { "type": "string", "description": "The `next_page_token` from the previous response." }, "page_size": { "type": "integer", "format": "int32", "description": "Tickets per page." } } }, "ListOrderTicketsResponse": { "type": "object", "properties": { "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/OrderTicket" }, "description": "The order's tickets." }, "next_page_token": { "type": "string", "description": "Token for the next page. Missing on the last page." } } }, "ListAllocationInventoriesRequest": { "type": "object", "required": [ "warehouse" ], "properties": { "warehouse": { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$", "description": "The warehouse to report on." }, "page_token": { "type": "string", "description": "The `next_page_token` from the previous response." }, "page_size": { "type": "integer", "format": "int32", "maximum": 5000, "description": "Rows per page." } } }, "ListAllocationInventoriesResponse": { "type": "object", "properties": { "allocation_inventories": { "type": "array", "items": { "$ref": "#/components/schemas/AllocationInventory" }, "description": "One row per product or bundle in the warehouse." }, "next_page_token": { "type": "string", "description": "Token for the next page. Missing on the last page." } } }, "ListTrackingsRequest": { "type": "object", "description": "Set only one of `tracking_number`, `order_id`, `external_order`.", "properties": { "tracking_number": { "type": "string", "description": "The tracking number printed on the label. A number issued later by the carrier won't match." }, "order_id": { "type": "string", "pattern": "^[A-Za-z0-9]{12}$", "description": "Bigblue order ID. Returns one tracking per parcel, without cancelled fulfillments." }, "external_order": { "$ref": "#/components/schemas/ExternalOrderId", "description": "Your order reference and the shop it came from. This is the only way to find an order by your own reference." } } }, "ListTrackingsResponse": { "type": "object", "properties": { "trackings": { "type": "array", "items": { "$ref": "#/components/schemas/Tracking" }, "description": "One tracking per parcel, with events newest first." } } }, "GetStorefrontAccessTokenRequest": { "type": "object", "properties": {} }, "GetStorefrontAccessTokenResponse": { "type": "object", "properties": { "token": { "type": "string", "description": "The storefront token. Safe to use in the browser." }, "expiry_time": { "type": "string", "description": "When the token expires, RFC 3339 UTC. Get a new one before then." } } }, "CreateReturnRequest": { "type": "object", "required": [ "return" ], "properties": { "return": { "$ref": "#/components/schemas/ReturnForm", "description": "The return to create." } } }, "CreateReturnResponse": { "type": "object", "properties": { "return": { "$ref": "#/components/schemas/Return", "description": "The new return with its `id` and `status`. Includes `label_url` if Bigblue created a return label." } } }, "UpdateReturnRequest": { "type": "object", "required": [ "return", "update_mask" ], "properties": { "return": { "$ref": "#/components/schemas/ReturnForm", "description": "The return, with `id` set. Only `resolution_status` and `manual_resolution` are read." }, "update_mask": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true, "description": "Fields to update. At least one, with no duplicates." } } }, "UpdateReturnResponse": { "type": "object", "properties": { "return": { "$ref": "#/components/schemas/Return", "description": "The updated return. `resolution_closed_time` is set when the resolution is `CLOSED`." } } }, "GetReturnRequest": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{12}RT[A-Za-z0-9]{2}$", "description": "Return ID, for example `BGBL0K3M9XQ2RT01`." } } }, "GetReturnResponse": { "type": "object", "properties": { "return": { "$ref": "#/components/schemas/Return", "description": "The return with its statuses, line items and inspection results." } } }, "ListReturnsRequest": { "type": "object", "description": "Set only one of `order`, `date_range`.", "properties": { "order": { "type": "string", "description": "Only return returns for this order. The date range is ignored when this is set." }, "date_range": { "$ref": "#/components/schemas/DateRange", "description": "Only return returns created in this period, RFC 3339 UTC." }, "page_token": { "type": "string", "description": "The `next_page_token` from the previous response." }, "page_size": { "type": "integer", "format": "int32", "description": "Returns per page. Uses a server default when `0` or missing." } } }, "ListReturnsResponse": { "type": "object", "properties": { "returns": { "type": "array", "items": { "$ref": "#/components/schemas/Return" }, "description": "The returns on this page." }, "next_page_token": { "type": "string", "description": "Token for the next page. Missing on the last page." } } }, "Error": { "type": "object", "description": "Every error has this format. Use `code` in your error handling. Several codes share an HTTP status, and the wording of `msg` can change.", "required": [ "code", "msg" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code.", "enum": [ "invalid_argument", "malformed", "out_of_range", "unauthenticated", "permission_denied", "resource_exhausted", "not_found", "bad_route", "already_exists", "aborted", "failed_precondition", "canceled", "deadline_exceeded", "unimplemented", "internal", "unknown", "unavailable", "data_loss" ] }, "msg": { "type": "string", "description": "Human-readable message for logs." }, "meta": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Extra details. Validation errors include `argument`, the path of the invalid field." } } } }, "responses": { "BadRequest": { "description": "A field is invalid or a value can't be parsed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "pattern": { "summary": "Value doesn't match the pattern", "value": { "code": "invalid_argument", "msg": "order.id value does not match regex pattern `^([[:alnum:]]{12}|)$`", "meta": { "argument": "order.id" } } }, "required": { "summary": "Missing required field", "value": { "code": "invalid_argument", "msg": "order.shipping_address is required", "meta": { "argument": "order.shipping_address" } } }, "unparseable": { "summary": "Amount can't be parsed", "value": { "code": "invalid_argument", "msg": "un-parseable amount '12,90 EUR'" } } } } } }, "Unauthenticated": { "description": "The `Authorization` header is missing or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No API key", "value": { "code": "unauthenticated", "msg": "api key must be included" } } } } } }, "Forbidden": { "description": "The API key isn't recognized or was revoked, or you exceeded the rate limit. Check `code` to tell them apart.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Key not recognized", "value": { "code": "permission_denied", "msg": "unauthorized" } }, "rateLimited": { "summary": "Rate limit exceeded", "value": { "code": "resource_exhausted", "msg": "You've exceeded your quota of requests per minute. Please try again in a few seconds." } } } } } }, "NotFound": { "description": "No object with this ID exists on your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "notFound": { "summary": "Not found", "value": { "code": "not_found", "msg": "not found" } } } } } }, "Conflict": { "description": "An object with this ID already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "exists": { "summary": "Duplicate ID", "value": { "code": "already_exists", "msg": "already exists" } } } } } }, "PreconditionFailed": { "description": "The object's current state doesn't allow this, for example cancelling a shipped order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "state": { "summary": "State doesn't allow it", "value": { "code": "failed_precondition", "msg": "order cannot be updated in status IN_PREPARATION" } } } } } }, "InternalError": { "description": "Server error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Server error", "value": { "code": "internal", "msg": "internal server error" } } } } } } } } }