{ "info": { "name": "Biklo Partner API", "description": "The Biklo Partner API, for company sellers and the platforms they run on.\n\nAuthentication: `Authorization: Bearer bk_live_…`. The environment is part of the key, so a test key presented to production is a 401 rather than a surprise.\n\nConventions: money is always MINOR units plus a currency (12550 = 125.50); timestamps are ISO 8601 UTC; lists are cursor-paginated and accept `updated_since` for incremental sync; every response carries `X-Request-Id`, which is the id to quote to support. Send an `Idempotency-Key` header on any write and a retry replays the first response instead of acting twice.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_key}}", "type": "string" } ] }, "variable": [ { "key": "base_url", "value": "https://sandbox-api.biklo.com", "type": "string" }, { "key": "api_key", "value": "bk_test_replace_me", "type": "string" } ], "item": [ { "name": "Addresses", "item": [ { "name": "Delete an address · DELETE /v1/addresses/{id}", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses", ":id" ], "query": [] }, "description": "Refused with `409 last_address` if it is your only one — every future order would lose its origin while your listings stayed up. Refused with `409 default_address` if it is the default and you have others; make another one default first.\n\nRequired scope: `company.write`." }, "response": [ { "name": "Delete an address — 200", "originalRequest": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses", ":id" ], "query": [] }, "description": "Refused with `409 last_address` if it is your only one — every future order would lose its origin while your listings stayed up. Refused with `409 default_address` if it is the default and you have others; make another one default first.\n\nRequired scope: `company.write`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"deleted\": true,\n \"id\": 4813\n}" } ] }, { "name": "List your addresses · GET /v1/addresses", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses" ], "query": [] }, "description": "Your own addresses, the default one first. The default is where every order ships FROM — we snapshot it as the parcel origin when an order is placed — and it is also the city, county and street a product is published with when you do not send a `city_id`. An account with no address cannot fulfil anything, so this is the first call a new integration should make.\n\nRequired scope: `company.read`." }, "response": [ { "name": "List your addresses — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses" ], "query": [] }, "description": "Your own addresses, the default one first. The default is where every order ships FROM — we snapshot it as the parcel origin when an order is placed — and it is also the city, county and street a product is published with when you do not send a `city_id`. An account with no address cannot fulfil anything, so this is the first call a new integration should make.\n\nRequired scope: `company.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"data\": [\n {\n \"id\": 4812,\n \"street\": \"Bulevardul Decebal 14\",\n \"postal_code\": \"200001\",\n \"city\": {\n \"id\": 1,\n \"name\": \"Craiova\"\n },\n \"county\": {\n \"id\": 1,\n \"name\": \"Dolj\"\n },\n \"country_code\": \"RO\",\n \"company_name\": \"Bike Shop SRL\",\n \"company_vat_code\": \"RO12345678\",\n \"company_reg_no\": \"J16/123/2020\",\n \"is_default\": true,\n \"created_at\": \"2026-09-14T09:12:44+00:00\",\n \"updated_at\": \"2026-09-14T09:12:44+00:00\"\n }\n ]\n}" } ] }, { "name": "Get one address · GET /v1/addresses/{id}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses", ":id" ], "query": [] }, "description": "A single address of yours. `404` for an id that is not on your account.\n\nRequired scope: `company.read`." }, "response": [ { "name": "Get one address — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses", ":id" ], "query": [] }, "description": "A single address of yours. `404` for an id that is not on your account.\n\nRequired scope: `company.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 4812,\n \"street\": \"Bulevardul Decebal 14\",\n \"postal_code\": \"200001\",\n \"city\": {\n \"id\": 1,\n \"name\": \"Craiova\"\n },\n \"county\": {\n \"id\": 1,\n \"name\": \"Dolj\"\n },\n \"country_code\": \"RO\",\n \"company_name\": \"Bike Shop SRL\",\n \"company_vat_code\": \"RO12345678\",\n \"company_reg_no\": \"J16/123/2020\",\n \"is_default\": true,\n \"created_at\": \"2026-09-14T09:12:44+00:00\",\n \"updated_at\": \"2026-09-14T09:12:44+00:00\"\n}" } ] }, { "name": "Create an address · POST /v1/addresses", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses" ], "query": [] }, "description": "Adds an address you can ship from. **Your first address automatically becomes the default**, whatever you send in `is_default` — a seller with one address and no default is a seller who cannot ship. The street must contain a number and the postal code must fit both the country format and the county the city is in; a courier rejects the shipment otherwise, so we reject it here instead.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"city_id\": 1,\n \"street\": \"Bulevardul Decebal 14\",\n \"postal_code\": \"200001\",\n \"is_default\": true\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Create an address — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses" ], "query": [] }, "description": "Adds an address you can ship from. **Your first address automatically becomes the default**, whatever you send in `is_default` — a seller with one address and no default is a seller who cannot ship. The street must contain a number and the postal code must fit both the country format and the county the city is in; a courier rejects the shipment otherwise, so we reject it here instead.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"city_id\": 1,\n \"street\": \"Bulevardul Decebal 14\",\n \"postal_code\": \"200001\",\n \"is_default\": true\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 4812,\n \"street\": \"Bulevardul Decebal 14\",\n \"postal_code\": \"200001\",\n \"city\": {\n \"id\": 1,\n \"name\": \"Craiova\"\n },\n \"county\": {\n \"id\": 1,\n \"name\": \"Dolj\"\n },\n \"country_code\": \"RO\",\n \"company_name\": \"Bike Shop SRL\",\n \"company_vat_code\": \"RO12345678\",\n \"company_reg_no\": \"J16/123/2020\",\n \"is_default\": true,\n \"created_at\": \"2026-09-14T09:12:44+00:00\",\n \"updated_at\": \"2026-09-14T09:12:44+00:00\"\n}" } ] }, { "name": "Make an address the default · POST /v1/addresses/{id}/default", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses/:id/default", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses", ":id", "default" ], "query": [] }, "description": "Makes this the address orders ship from, and clears the flag on every other one. This is the setting that decides where a courier collects, and which city a product with no `city_id` is published in — change it and your next product sync moves the catalogue with it.\n\nRequired scope: `company.write`." }, "response": [ { "name": "Make an address the default — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses/:id/default", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses", ":id", "default" ], "query": [] }, "description": "Makes this the address orders ship from, and clears the flag on every other one. This is the setting that decides where a courier collects, and which city a product with no `city_id` is published in — change it and your next product sync moves the catalogue with it.\n\nRequired scope: `company.write`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 4813,\n \"street\": \"Strada Depozitului 9\",\n \"postal_code\": \"600001\",\n \"city\": {\n \"id\": 385,\n \"name\": \"Bacau\"\n },\n \"county\": {\n \"id\": 2,\n \"name\": \"Bacau\"\n },\n \"country_code\": \"RO\",\n \"company_name\": \"Bike Shop SRL\",\n \"company_vat_code\": \"RO12345678\",\n \"company_reg_no\": \"J16/123/2020\",\n \"is_default\": true,\n \"created_at\": \"2026-09-14T09:40:10+00:00\",\n \"updated_at\": \"2026-09-14T11:20:55+00:00\"\n}" } ] }, { "name": "Update an address · PUT /v1/addresses/{id}", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses", ":id" ], "query": [] }, "description": "Partial — send only what changes. The result is re-validated as a whole address, not just the fields you sent: moving the city without moving the postal code is rejected, because the stored code no longer belongs to the new county. Returns the complete address.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"street\": \"Bulevardul Decebal 16\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Update an address — 200", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/addresses/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "addresses", ":id" ], "query": [] }, "description": "Partial — send only what changes. The result is re-validated as a whole address, not just the fields you sent: moving the city without moving the postal code is rejected, because the stored code no longer belongs to the new county. Returns the complete address.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"street\": \"Bulevardul Decebal 16\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 4812,\n \"street\": \"Bulevardul Decebal 16\",\n \"postal_code\": \"200001\",\n \"city\": {\n \"id\": 1,\n \"name\": \"Craiova\"\n },\n \"county\": {\n \"id\": 1,\n \"name\": \"Dolj\"\n },\n \"country_code\": \"RO\",\n \"company_name\": \"Bike Shop SRL\",\n \"company_vat_code\": \"RO12345678\",\n \"company_reg_no\": \"J16/123/2020\",\n \"is_default\": true,\n \"created_at\": \"2026-09-14T09:12:44+00:00\",\n \"updated_at\": \"2026-09-14T11:03:02+00:00\"\n}" } ] } ] }, { "name": "Catalog", "item": [ { "name": "List the category tree · GET /v1/categories", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/categories?lang=ro&parent_id=", "host": [ "{{base_url}}" ], "path": [ "v1", "categories" ], "query": [ { "key": "lang", "value": "ro", "description": "Language code from GET /v1/languages", "disabled": false }, { "key": "parent_id", "value": "", "description": "Only the children of this category", "disabled": true } ] }, "description": "The whole tree in one response — an ERP caches it. `id` is the Romanian master id and never changes between languages; `tid` is the row in the language you asked for. Only leaves accept listings. Each category carries its `commission` — the rate Biklo charges a company seller here, inherited down the tree — so you can set margins before listing rather than inferring the fee from a completed order. `max_amount: null` means UNCAPPED.\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "List the category tree — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/categories?lang=ro&parent_id=", "host": [ "{{base_url}}" ], "path": [ "v1", "categories" ], "query": [ { "key": "lang", "value": "ro", "description": "Language code from GET /v1/languages", "disabled": false }, { "key": "parent_id", "value": "", "description": "Only the children of this category", "disabled": true } ] }, "description": "The whole tree in one response — an ERP caches it. `id` is the Romanian master id and never changes between languages; `tid` is the row in the language you asked for. Only leaves accept listings. Each category carries its `commission` — the rate Biklo charges a company seller here, inherited down the tree — so you can set margins before listing rather than inferring the fee from a completed order. `max_amount: null` means UNCAPPED.\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"language\": \"ro\",\n \"count\": 210,\n \"data\": [\n {\n \"id\": 4291,\n \"tid\": 4291,\n \"parent_id\": 5,\n \"name\": \"Hardtail\",\n \"slug\": \"hardtail\",\n \"depth\": 2,\n \"is_leaf\": true,\n \"shipping\": {\n \"can_be_shipped\": true,\n \"default_weight_kg\": 14\n }\n }\n ]\n}" } ] }, { "name": "Attributes for a category · GET /v1/categories/{id}/attributes", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/categories/:id/attributes?lang=ro", "host": [ "{{base_url}}" ], "path": [ "v1", "categories", ":id", "attributes" ], "query": [ { "key": "lang", "value": "ro", "description": "Language for names and option values", "disabled": false } ] }, "description": "The attributes a listing in this category must carry, including everything inherited from parent categories. Nothing can be published until the required ones are supplied — send these ids back in `attributes` when creating a product.\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "Attributes for a category — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/categories/:id/attributes?lang=ro", "host": [ "{{base_url}}" ], "path": [ "v1", "categories", ":id", "attributes" ], "query": [ { "key": "lang", "value": "ro", "description": "Language for names and option values", "disabled": false } ] }, "description": "The attributes a listing in this category must carry, including everything inherited from parent categories. Nothing can be published until the required ones are supplied — send these ids back in `attributes` when creating a product.\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"category_id\": 4291,\n \"language\": \"ro\",\n \"count\": 9,\n \"data\": [\n {\n \"id\": 32,\n \"tid\": 32,\n \"name\": \"Brand\",\n \"slug\": \"brand\",\n \"type\": \"checkbox_multiple\",\n \"required\": true,\n \"options\": [\n {\n \"id\": 226,\n \"tid\": 226,\n \"value\": \"Avid\",\n \"slug\": \"avid\"\n }\n ]\n }\n ]\n}" } ] }, { "name": "Selling countries · GET /v1/countries", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/countries", "host": [ "{{base_url}}" ], "path": [ "v1", "countries" ], "query": [] }, "description": "Countries the marketplace sells in, with the currency each uses.\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "Selling countries — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/countries", "host": [ "{{base_url}}" ], "path": [ "v1", "countries" ], "query": [] }, "description": "Countries the marketplace sells in, with the currency each uses.\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 32,\n \"data\": [\n {\n \"code\": \"RO\",\n \"name\": \"Romania\",\n \"currency\": \"RON\",\n \"phone_prefix\": \"40\"\n }\n ]\n}" } ] }, { "name": "Currencies · GET /v1/currencies", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/currencies", "host": [ "{{base_url}}" ], "path": [ "v1", "currencies" ], "query": [] }, "description": "`decimals` is the exponent for the minor units every amount in this API uses: 12550 with decimals 2 is 125.50.\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "Currencies — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/currencies", "host": [ "{{base_url}}" ], "path": [ "v1", "currencies" ], "query": [] }, "description": "`decimals` is the exponent for the minor units every amount in this API uses: 12550 with decimals 2 is 125.50.\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 170,\n \"data\": [\n {\n \"code\": \"RON\",\n \"name\": \"Romanian Leu\",\n \"symbol\": \"lei\",\n \"decimals\": 2,\n \"symbol_before_amount\": false\n }\n ]\n}" } ] }, { "name": "Published languages · GET /v1/languages", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/languages", "host": [ "{{base_url}}" ], "path": [ "v1", "languages" ], "query": [] }, "description": "The languages the catalog is available in. Pass one as `?lang=` to the category endpoints.\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "Published languages — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/languages", "host": [ "{{base_url}}" ], "path": [ "v1", "languages" ], "query": [] }, "description": "The languages the catalog is available in. Pass one as `?lang=` to the category endpoints.\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 24,\n \"data\": [\n {\n \"code\": \"ro\",\n \"name\": \"Romanian\",\n \"native_name\": \"Română\",\n \"is_default\": true\n }\n ]\n}" } ] } ] }, { "name": "Company", "item": [ { "name": "Delete a pickup point · DELETE /v1/company/pickup-points/{id}", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/pickup-points/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "pickup-points", ":id" ], "query": [] }, "description": "Refused with 409 if it is the default and you have others — make another one default first, so drop-shipped orders never lose their origin.\n\nRequired scope: `company.write`." }, "response": [ { "name": "Delete a pickup point — 200", "originalRequest": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/pickup-points/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "pickup-points", ":id" ], "query": [] }, "description": "Refused with 409 if it is the default and you have others — make another one default first, so drop-shipped orders never lose their origin.\n\nRequired scope: `company.write`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"deleted\": true,\n \"id\": 11\n}" } ] }, { "name": "Your company profile · GET /v1/company", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company", "host": [ "{{base_url}}" ], "path": [ "v1", "company" ], "query": [] }, "description": "The public shop profile, the settings that change how your orders behave, and the countries you sell into. Returns 403 `not_a_company` for a private seller.\n\nRequired scope: `company.read`." }, "response": [ { "name": "Your company profile — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company", "host": [ "{{base_url}}" ], "path": [ "v1", "company" ], "query": [] }, "description": "The public shop profile, the settings that change how your orders behave, and the countries you sell into. Returns 403 `not_a_company` for a private seller.\n\nRequired scope: `company.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"company\": {\n \"id\": 9000010,\n \"name\": \"Example Bikes SL\",\n \"business_name\": \"Example Bikes SL\",\n \"title\": \"Example Bikes\",\n \"description\": \"

Mountain bike apparel from Barcelona.

\",\n \"logo_url\": null,\n \"cover_url\": null,\n \"contact\": {\n \"person\": \"Sandbox Contact\",\n \"email\": \"contact@example.com\",\n \"phone\": \"0700000000\",\n \"address\": \"Carrer Gran 42, Barcelona\"\n },\n \"links\": {\n \"website\": \"https://example.com\",\n \"marketplace\": null,\n \"google_maps\": null,\n \"facebook\": null,\n \"instagram\": null,\n \"linkedin\": null,\n \"tiktok\": null,\n \"youtube\": null\n },\n \"is_active\": true,\n \"onboarding_completed_at\": \"2026-08-02T09:14:00Z\"\n },\n \"settings\": {\n \"allow_price_negotiation\": true,\n \"fees\": {\n \"absorb_platform_fee\": false,\n \"absorb_shipping_local\": true,\n \"absorb_shipping_international\": false,\n \"absorption_is_locked\": true\n },\n \"shipping\": {\n \"can_ship_with_us\": true\n }\n },\n \"selling_countries\": [\n {\n \"country_id\": 70,\n \"code\": \"ES\",\n \"name\": \"España\",\n \"currency\": \"EUR\"\n }\n ]\n}" } ] }, { "name": "Verification documents · GET /v1/company/documents", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/documents", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "documents" ], "query": [] }, "description": "Status only — whether each filed document was accepted, and why not if it was rejected. The files themselves are identity papers and are not downloadable through the API.\n\nRequired scope: `company.read`." }, "response": [ { "name": "Verification documents — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/documents", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "documents" ], "query": [] }, "description": "Status only — whether each filed document was accepted, and why not if it was rejected. The files themselves are identity papers and are not downloadable through the API.\n\nRequired scope: `company.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"data\": [\n {\n \"id\": 3,\n \"type\": \"company_registration\",\n \"file_name\": \"registro.pdf\",\n \"status\": \"approved\",\n \"reject_reason\": null,\n \"uploaded_at\": \"2026-08-01T10:00:00Z\"\n }\n ]\n}" } ] }, { "name": "Fiscal and banking details · GET /v1/company/financial-data", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/financial-data", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "financial-data" ], "query": [] }, "description": "Read-only. One entry per selling country, because a company selling into three countries may invoice from three legal entities. These appear on invoices and are changed in the seller dashboard, where they go through verification.\n\nRequired scope: `company.read`." }, "response": [ { "name": "Fiscal and banking details — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/financial-data", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "financial-data" ], "query": [] }, "description": "Read-only. One entry per selling country, because a company selling into three countries may invoice from three legal entities. These appear on invoices and are changed in the seller dashboard, where they go through verification.\n\nRequired scope: `company.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"data\": [\n {\n \"id\": 1,\n \"country_code\": \"ES\",\n \"business_name\": \"Example Bikes SL\",\n \"registration_number\": \"B12345678\",\n \"vat_id\": \"ESB12345678\",\n \"iban\": \"ES91…\",\n \"address\": {\n \"street\": \"Carrer Gran 42\",\n \"city\": \"Barcelona\",\n \"postal_code\": \"08001\",\n \"country_code\": \"ES\"\n },\n \"is_default\": true\n }\n ]\n}" } ] }, { "name": "List pickup points · GET /v1/company/pickup-points", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/pickup-points", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "pickup-points" ], "query": [] }, "description": "The addresses a courier collects from. A pickup point is also the origin for drop-shipped orders and the address returns travel back to.\n\nRequired scope: `company.read`." }, "response": [ { "name": "List pickup points — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/pickup-points", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "pickup-points" ], "query": [] }, "description": "The addresses a courier collects from. A pickup point is also the origin for drop-shipped orders and the address returns travel back to.\n\nRequired scope: `company.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"data\": [\n {\n \"id\": 11,\n \"label\": \"Barcelona warehouse\",\n \"type\": \"warehouse\",\n \"address\": {\n \"street\": \"Carrer Gran 42\",\n \"city\": \"Barcelona\",\n \"county\": \"Barcelona\",\n \"postal_code\": \"08001\",\n \"country_code\": \"ES\"\n },\n \"contact\": {\n \"phone\": \"+34600000000\",\n \"email\": \"wh@example.com\"\n },\n \"is_default\": true,\n \"is_active\": true\n }\n ]\n}" } ] }, { "name": "Countries you sell into · GET /v1/company/selling-countries", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/selling-countries", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "selling-countries" ], "query": [] }, "description": "You can only add pickup points, absorption bands and listings for these. Changing the list is a commercial decision made in the dashboard.\n\nRequired scope: `company.read`." }, "response": [ { "name": "Countries you sell into — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/selling-countries", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "selling-countries" ], "query": [] }, "description": "You can only add pickup points, absorption bands and listings for these. Changing the list is a commercial decision made in the dashboard.\n\nRequired scope: `company.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"data\": [\n {\n \"country_id\": 70,\n \"code\": \"ES\",\n \"name\": \"España\",\n \"currency\": \"EUR\"\n }\n ]\n}" } ] }, { "name": "Read your delivery bands · GET /v1/company/shipping-absorption", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/shipping-absorption", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "shipping-absorption" ], "query": [] }, "description": "Per destination country AND per parcel size: above a threshold you pay the courier, below it the buyer pays at checkout. Bands compare the SELLER-GROUP subtotal — shipping is one charge per seller per order — not a single product's price. Each destination carries TWO independent sets, one per `parcel_tier`, because the courier prices them very differently: a small RO→HU parcel costs about 26 RON and a large one about 539. The response includes `band_rules`, which is worth reading before you write.\n\nRequired scope: `company.read`." }, "response": [ { "name": "Read your delivery bands — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/shipping-absorption", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "shipping-absorption" ], "query": [] }, "description": "Per destination country AND per parcel size: above a threshold you pay the courier, below it the buyer pays at checkout. Bands compare the SELLER-GROUP subtotal — shipping is one charge per seller per order — not a single product's price. Each destination carries TWO independent sets, one per `parcel_tier`, because the courier prices them very differently: a small RO→HU parcel costs about 26 RON and a large one about 539. The response includes `band_rules`, which is worth reading before you write.\n\nRequired scope: `company.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"sets\": [\n {\n \"country_code\": \"HU\",\n \"scope\": \"international\",\n \"parcel_tier\": \"small\",\n \"currency\": \"EUR\",\n \"bands\": [\n {\n \"min_amount\": 0,\n \"max_amount\": 50000,\n \"absorbs\": false\n },\n {\n \"min_amount\": 50000,\n \"max_amount\": null,\n \"absorbs\": true\n }\n ]\n },\n {\n \"country_code\": \"HU\",\n \"scope\": \"international\",\n \"parcel_tier\": \"large\",\n \"currency\": \"EUR\",\n \"bands\": [\n {\n \"min_amount\": 0,\n \"max_amount\": null,\n \"absorbs\": false\n }\n ]\n }\n ],\n \"parcel_tiers\": {\n \"small\": \"Accessories and small parcels — billed on the small-courier tariff.\",\n \"large\": \"Bikes, large and extra-large items — the expensive tariff.\"\n },\n \"note\": \"Bands compare the seller-group subtotal, in minor units. A band with absorbs=false means the buyer pays delivery at checkout. Each destination has a SEPARATE set per parcel_tier — writing one does not touch the other.\",\n \"band_rules\": {\n \"bands_are_half_open\": \"Each band covers [min_amount, max_amount) — max is exclusive.\",\n \"must_be_contiguous\": \"A band's max_amount must equal the next band's min_amount. Not max-1.\",\n \"first_band_starts_at_zero\": true,\n \"last_band_is_open_ended\": \"The last band must have max_amount: null.\",\n \"example\": {\n \"country_code\": \"RO\",\n \"parcel_tier\": \"small\",\n \"currency\": \"RON\",\n \"bands\": [\n {\n \"min_amount\": 0,\n \"max_amount\": 50000,\n \"absorbs\": false\n },\n {\n \"min_amount\": 50000,\n \"max_amount\": null,\n \"absorbs\": true\n }\n ]\n }\n },\n \"selling_countries\": [\n {\n \"country_id\": 70,\n \"code\": \"ES\",\n \"name\": \"España\",\n \"currency\": \"EUR\"\n }\n ]\n}" } ] }, { "name": "Upload the shop logo · POST /v1/company/logo", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/logo", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "logo" ], "query": [] }, "description": "Multipart `file` — PNG, JPG or WebP. Resized and stored the same way the seller dashboard stores it.\n\nRequired scope: `company.write`." }, "response": [ { "name": "Upload the shop logo — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/logo", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "logo" ], "query": [] }, "description": "Multipart `file` — PNG, JPG or WebP. Resized and stored the same way the seller dashboard stores it.\n\nRequired scope: `company.write`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"company\": {\n \"id\": 9000010,\n \"name\": \"Example Bikes SL\",\n \"business_name\": \"Example Bikes SL\",\n \"title\": \"Example Bikes\",\n \"description\": \"

Mountain bike apparel from Barcelona.

\",\n \"logo_url\": \"https://cdn.biklo.ro/app/companies/5611/logo.png\",\n \"cover_url\": null,\n \"contact\": {\n \"person\": \"Sandbox Contact\",\n \"email\": \"contact@example.com\",\n \"phone\": \"0700000000\",\n \"address\": \"Carrer Gran 42, Barcelona\"\n },\n \"links\": {\n \"website\": \"https://example.com\",\n \"marketplace\": null,\n \"google_maps\": null,\n \"facebook\": null,\n \"instagram\": null,\n \"linkedin\": null,\n \"tiktok\": null,\n \"youtube\": null\n },\n \"is_active\": true,\n \"onboarding_completed_at\": \"2026-08-02T09:14:00Z\"\n }\n}" } ] }, { "name": "Create a pickup point · POST /v1/company/pickup-points", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/pickup-points", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "pickup-points" ], "query": [] }, "description": "Address rules apply exactly as they do for a delivery: the street must contain a number, the postal code must fit the country and county, and the country must be one you sell into. Get `city_id` from GET /v1/geo/cities. The first point you create becomes the default.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"label\": \"Barcelona warehouse\",\n \"country_code\": \"ES\",\n \"city_id\": 665904,\n \"street\": \"Carrer Gran 42\",\n \"postal_code\": \"08001\",\n \"contact_phone\": \"+34600000000\",\n \"contact_email\": \"warehouse@example.com\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Create a pickup point — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/pickup-points", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "pickup-points" ], "query": [] }, "description": "Address rules apply exactly as they do for a delivery: the street must contain a number, the postal code must fit the country and county, and the country must be one you sell into. Get `city_id` from GET /v1/geo/cities. The first point you create becomes the default.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"label\": \"Barcelona warehouse\",\n \"country_code\": \"ES\",\n \"city_id\": 665904,\n \"street\": \"Carrer Gran 42\",\n \"postal_code\": \"08001\",\n \"contact_phone\": \"+34600000000\",\n \"contact_email\": \"warehouse@example.com\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 11,\n \"label\": \"Barcelona warehouse\",\n \"type\": \"warehouse\",\n \"address\": {\n \"street\": \"Carrer Gran 42\",\n \"city\": \"Barcelona\",\n \"county\": \"Barcelona\",\n \"postal_code\": \"08001\",\n \"country_code\": \"ES\"\n },\n \"contact\": {\n \"phone\": \"+34600000000\",\n \"email\": \"wh@example.com\"\n },\n \"is_default\": true,\n \"is_active\": true\n}" } ] }, { "name": "Update the profile · PUT /v1/company", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company", "host": [ "{{base_url}}" ], "path": [ "v1", "company" ], "query": [] }, "description": "Presentation fields only: description, contact details and links. Your legal identity — business name, fiscal codes, IBAN — is not editable here; it appears on invoices and changes through verification in the seller dashboard. Sending a field outside the editable set returns 400 with the list of what is allowed.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"description\": \"

Mountain bike apparel from Barcelona.

\",\n \"website\": \"https://example.com\",\n \"phone\": \"+34600000000\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Update the profile — 200", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company", "host": [ "{{base_url}}" ], "path": [ "v1", "company" ], "query": [] }, "description": "Presentation fields only: description, contact details and links. Your legal identity — business name, fiscal codes, IBAN — is not editable here; it appears on invoices and changes through verification in the seller dashboard. Sending a field outside the editable set returns 400 with the list of what is allowed.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"description\": \"

Mountain bike apparel from Barcelona.

\",\n \"website\": \"https://example.com\",\n \"phone\": \"+34600000000\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"company\": {\n \"id\": 9000010,\n \"name\": \"Example Bikes SL\",\n \"business_name\": \"Example Bikes SL\",\n \"title\": \"Example Bikes\",\n \"description\": \"

Mountain bike apparel from Barcelona.

\",\n \"logo_url\": null,\n \"cover_url\": null,\n \"contact\": {\n \"person\": \"Sandbox Contact\",\n \"email\": \"contact@example.com\",\n \"phone\": \"0700000000\",\n \"address\": \"Carrer Gran 42, Barcelona\"\n },\n \"links\": {\n \"website\": \"https://example.com\",\n \"marketplace\": null,\n \"google_maps\": null,\n \"facebook\": null,\n \"instagram\": null,\n \"linkedin\": null,\n \"tiktok\": null,\n \"youtube\": null\n },\n \"is_active\": true,\n \"onboarding_completed_at\": \"2026-08-02T09:14:00Z\"\n }\n}" } ] }, { "name": "Update a pickup point · PUT /v1/company/pickup-points/{id}", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/pickup-points/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "pickup-points", ":id" ], "query": [] }, "description": "Partial — send only what changes. Any address field you do send is re-validated.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"label\": \"Barcelona main warehouse\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Update a pickup point — 200", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/pickup-points/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "pickup-points", ":id" ], "query": [] }, "description": "Partial — send only what changes. Any address field you do send is re-validated.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"label\": \"Barcelona main warehouse\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 11,\n \"label\": \"Barcelona main warehouse\",\n \"type\": \"warehouse\",\n \"address\": {\n \"street\": \"Carrer Gran 42\",\n \"city\": \"Barcelona\",\n \"county\": \"Barcelona\",\n \"postal_code\": \"08001\",\n \"country_code\": \"ES\"\n },\n \"contact\": {\n \"phone\": \"+34600000000\",\n \"email\": \"wh@example.com\"\n },\n \"is_default\": true,\n \"is_active\": true\n}" } ] }, { "name": "Update order settings · PUT /v1/company/settings", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/settings", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "settings" ], "query": [] }, "description": "Today the only writable setting is `allow_price_negotiation` — whether buyers may send price offers on your listings. Fee absorption is changed through /v1/company/shipping-absorption, because it carries rules a toggle cannot express.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"allow_price_negotiation\": true\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Update order settings — 200", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/settings", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "settings" ], "query": [] }, "description": "Today the only writable setting is `allow_price_negotiation` — whether buyers may send price offers on your listings. Fee absorption is changed through /v1/company/shipping-absorption, because it carries rules a toggle cannot express.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"allow_price_negotiation\": true\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"settings\": {\n \"allow_price_negotiation\": true,\n \"fees\": {\n \"absorb_platform_fee\": false,\n \"absorb_shipping_local\": true,\n \"absorb_shipping_international\": false,\n \"absorption_is_locked\": true\n },\n \"shipping\": {\n \"can_ship_with_us\": true\n }\n }\n}" } ] }, { "name": "Set your delivery bands · PUT /v1/company/shipping-absorption", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/shipping-absorption", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "shipping-absorption" ], "query": [] }, "description": "Replaces the whole set for one country, scope AND parcel_tier. `parcel_tier` is REQUIRED: each destination carries two independent sets and writing one does not touch the other, so a default would quietly rewrite the small-parcel bands while you believed you had set both. Bands are half-open [min, max): a band's `max_amount` must EQUAL the next band's `min_amount` — writing 49999 then 50000 leaves a one-cent hole and the set is refused. The first band starts at 0, the last has `max_amount: null`. Amounts are in minor units. An empty `bands` array means you absorb delivery on everything.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"country_code\": \"ES\",\n \"scope\": \"local\",\n \"parcel_tier\": \"large\",\n \"currency\": \"EUR\",\n \"bands\": [\n {\n \"min_amount\": 0,\n \"max_amount\": 50000,\n \"absorbs\": false\n },\n {\n \"min_amount\": 50000,\n \"max_amount\": null,\n \"absorbs\": true\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Set your delivery bands — 200", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/company/shipping-absorption", "host": [ "{{base_url}}" ], "path": [ "v1", "company", "shipping-absorption" ], "query": [] }, "description": "Replaces the whole set for one country, scope AND parcel_tier. `parcel_tier` is REQUIRED: each destination carries two independent sets and writing one does not touch the other, so a default would quietly rewrite the small-parcel bands while you believed you had set both. Bands are half-open [min, max): a band's `max_amount` must EQUAL the next band's `min_amount` — writing 49999 then 50000 leaves a one-cent hole and the set is refused. The first band starts at 0, the last has `max_amount: null`. Amounts are in minor units. An empty `bands` array means you absorb delivery on everything.\n\nRequired scope: `company.write`.", "body": { "mode": "raw", "raw": "{\n \"country_code\": \"ES\",\n \"scope\": \"local\",\n \"parcel_tier\": \"large\",\n \"currency\": \"EUR\",\n \"bands\": [\n {\n \"min_amount\": 0,\n \"max_amount\": 50000,\n \"absorbs\": false\n },\n {\n \"min_amount\": 50000,\n \"max_amount\": null,\n \"absorbs\": true\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"sets\": [\n {\n \"country_code\": \"HU\",\n \"scope\": \"international\",\n \"parcel_tier\": \"small\",\n \"currency\": \"EUR\",\n \"bands\": [\n {\n \"min_amount\": 0,\n \"max_amount\": 50000,\n \"absorbs\": false\n },\n {\n \"min_amount\": 50000,\n \"max_amount\": null,\n \"absorbs\": true\n }\n ]\n },\n {\n \"country_code\": \"HU\",\n \"scope\": \"international\",\n \"parcel_tier\": \"large\",\n \"currency\": \"EUR\",\n \"bands\": [\n {\n \"min_amount\": 0,\n \"max_amount\": null,\n \"absorbs\": false\n }\n ]\n }\n ],\n \"parcel_tiers\": {\n \"small\": \"Accessories and small parcels — billed on the small-courier tariff.\",\n \"large\": \"Bikes, large and extra-large items — the expensive tariff.\"\n },\n \"note\": \"Bands compare the seller-group subtotal, in minor units. A band with absorbs=false means the buyer pays delivery at checkout. Each destination has a SEPARATE set per parcel_tier — writing one does not touch the other.\",\n \"band_rules\": {\n \"bands_are_half_open\": \"Each band covers [min_amount, max_amount) — max is exclusive.\",\n \"must_be_contiguous\": \"A band's max_amount must equal the next band's min_amount. Not max-1.\",\n \"first_band_starts_at_zero\": true,\n \"last_band_is_open_ended\": \"The last band must have max_amount: null.\",\n \"example\": {\n \"country_code\": \"RO\",\n \"parcel_tier\": \"small\",\n \"currency\": \"RON\",\n \"bands\": [\n {\n \"min_amount\": 0,\n \"max_amount\": 50000,\n \"absorbs\": false\n },\n {\n \"min_amount\": 50000,\n \"max_amount\": null,\n \"absorbs\": true\n }\n ]\n }\n },\n \"selling_countries\": [\n {\n \"country_id\": 70,\n \"code\": \"ES\",\n \"name\": \"España\",\n \"currency\": \"EUR\"\n }\n ]\n}" } ] } ] }, { "name": "Customers", "item": [ { "name": "List your customers · GET /v1/customers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/customers?updated_since=&q=&limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "customers" ], "query": [ { "key": "updated_since", "value": "", "description": "ISO 8601. A customer counts as changed when any of their orders did — a status moving to delivered is usually what makes you want to invoice.", "disabled": true }, { "key": "q", "value": "", "description": "Match on name or email.", "disabled": true }, { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor from the previous page", "disabled": true } ] }, "description": "Everyone who has ordered from you, keyed on the buyer rather than the order, with the billing details from their most recent order. This is what `POST /v1/orders/{id}/invoice` never gave you: the order payload carries a delivery block because a courier needs a city and a postcode, and an invoice needs a street — and, for a business buyer, a company name and a VAT number. You only ever see buyers you have actually sold to.\n\nRequired scope: `customers.read`." }, "response": [ { "name": "List your customers — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/customers?updated_since=&q=&limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "customers" ], "query": [ { "key": "updated_since", "value": "", "description": "ISO 8601. A customer counts as changed when any of their orders did — a status moving to delivered is usually what makes you want to invoice.", "disabled": true }, { "key": "q", "value": "", "description": "Match on name or email.", "disabled": true }, { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor from the previous page", "disabled": true } ] }, "description": "Everyone who has ordered from you, keyed on the buyer rather than the order, with the billing details from their most recent order. This is what `POST /v1/orders/{id}/invoice` never gave you: the order payload carries a delivery block because a courier needs a city and a postcode, and an invoice needs a street — and, for a business buyer, a company name and a VAT number. You only ever see buyers you have actually sold to.\n\nRequired scope: `customers.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": 98853,\n \"data\": [\n {\n \"id\": 9000001,\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+40700000000\",\n \"orders_count\": 3,\n \"first_order_at\": \"2026-03-02T11:40:19Z\",\n \"last_order_at\": \"2026-09-08T14:08:52Z\",\n \"billing\": {\n \"address_line\": \"Str. Exemplu 12\",\n \"city\": \"Brasov\",\n \"county\": \"Brasov\",\n \"postal_code\": \"500002\",\n \"country_code\": \"RO\",\n \"country\": \"România\",\n \"is_company\": true,\n \"company\": {\n \"name\": \"Example Bike Shop SRL\",\n \"vat_code\": \"RO12345678\",\n \"registration_no\": \"J16/123/2020\"\n },\n \"is_live\": true,\n \"delivered_to_locker\": false\n }\n }\n ]\n}" } ] }, { "name": "One customer and their orders · GET /v1/customers/{id}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/customers/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "customers", ":id" ], "query": [] }, "description": "A buyer, their billing details, and every order they have placed with you — each flagged with whether it already carries an invoice, so a nightly job can pick up exactly the ones it has not billed. A buyer who has never ordered from you is `customer_not_found` (404), which is also what stops you reaching anyone else's customers.\n\nRequired scope: `customers.read`." }, "response": [ { "name": "One customer and their orders — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/customers/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "customers", ":id" ], "query": [] }, "description": "A buyer, their billing details, and every order they have placed with you — each flagged with whether it already carries an invoice, so a nightly job can pick up exactly the ones it has not billed. A buyer who has never ordered from you is `customer_not_found` (404), which is also what stops you reaching anyone else's customers.\n\nRequired scope: `customers.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 9000001,\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+40700000000\",\n \"orders_count\": 2,\n \"first_order_at\": \"2026-03-02T11:40:19Z\",\n \"last_order_at\": \"2026-09-08T14:08:52Z\",\n \"billing\": {\n \"address_line\": \"Str. Exemplu 12\",\n \"city\": \"Brasov\",\n \"county\": \"Brasov\",\n \"postal_code\": \"500002\",\n \"country_code\": \"RO\",\n \"country\": \"România\",\n \"is_company\": true,\n \"company\": {\n \"name\": \"Example Bike Shop SRL\",\n \"vat_code\": \"RO12345678\",\n \"registration_no\": \"J16/123/2020\"\n },\n \"is_live\": true,\n \"delivered_to_locker\": false\n },\n \"orders\": [\n {\n \"id\": 690,\n \"reference\": \"ERP-1042\",\n \"status\": \"delivered\",\n \"total\": {\n \"amount\": 4698,\n \"currency\": \"RON\"\n },\n \"has_invoice\": false,\n \"created_at\": \"2026-09-08T14:08:52Z\"\n }\n ]\n}" } ] } ] }, { "name": "Fee-liabilities", "item": [ { "name": "Fees you owe, per order · GET /v1/fee-liabilities", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/fee-liabilities?limit=50&cursor=&status=settled&order_id=721", "host": [ "{{base_url}}" ], "path": [ "v1", "fee-liabilities" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "status", "value": "settled", "description": "pending, settled or cancelled", "disabled": false }, { "key": "order_id", "value": "721", "description": "Only liabilities for one order", "disabled": false } ] }, "description": "A liability exists from the moment an order settles and is invoiced later in a batch, so this is where most of a current month lives — before any document exists. `owed_amount` and `charged_amount` differ whenever a liability settled PARTIALLY; reading one and assuming the other is how books stop balancing.\n\nRequired scope: `wallet.read`." }, "response": [ { "name": "Fees you owe, per order — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/fee-liabilities?limit=50&cursor=&status=settled&order_id=721", "host": [ "{{base_url}}" ], "path": [ "v1", "fee-liabilities" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "status", "value": "settled", "description": "pending, settled or cancelled", "disabled": false }, { "key": "order_id", "value": "721", "description": "Only liabilities for one order", "disabled": false } ] }, "description": "A liability exists from the moment an order settles and is invoiced later in a batch, so this is where most of a current month lives — before any document exists. `owed_amount` and `charged_amount` differ whenever a liability settled PARTIALLY; reading one and assuming the other is how books stop balancing.\n\nRequired scope: `wallet.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 2,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": 17,\n \"order_id\": 721,\n \"currency\": \"RON\",\n \"owed_amount\": 500,\n \"charged_amount\": 0,\n \"written_off_amount\": 0,\n \"platform_fee_amount\": 500,\n \"shipping_fee_amount\": 0,\n \"status\": \"pending\",\n \"settled_at\": null,\n \"invoice\": null\n },\n {\n \"id\": 15,\n \"order_id\": 718,\n \"currency\": \"RON\",\n \"owed_amount\": 3050,\n \"charged_amount\": 2700,\n \"written_off_amount\": 350,\n \"platform_fee_amount\": 1800,\n \"shipping_fee_amount\": 1250,\n \"status\": \"settled\",\n \"settled_at\": \"2026-09-12T08:09:40Z\",\n \"invoice\": {\n \"series\": \"RO_BK_COM\",\n \"number\": \"0524\",\n \"pdf_url\": \"/v1/invoices/0524/pdf?series=RO_BK_COM\"\n }\n }\n ]\n}" } ] } ] }, { "name": "Getting started", "item": [ { "name": "Who am I · GET /v1/me", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/me", "host": [ "{{base_url}}" ], "path": [ "v1", "me" ], "query": [] }, "description": "The first call any integration makes: which environment you are talking to, which seller the key acts for, and what it may do. No scope required — a key can always describe itself.\n\nNo scope required." }, "response": [ { "name": "Who am I — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/me", "host": [ "{{base_url}}" ], "path": [ "v1", "me" ], "query": [] }, "description": "The first call any integration makes: which environment you are talking to, which seller the key acts for, and what it may do. No scope required — a key can always describe itself.\n\nNo scope required." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"api_version\": \"v1\",\n \"environment\": \"test\",\n \"is_sandbox\": true,\n \"app\": {\n \"id\": 1,\n \"name\": \"EasySales (pilot)\",\n \"vendor\": \"easysales\"\n },\n \"key\": {\n \"public_id\": \"88e2fb06233a\",\n \"scopes\": [\n \"catalog.read\",\n \"products.read\"\n ],\n \"expires_at\": null\n },\n \"seller\": {\n \"user_id\": 22,\n \"name\": \"Bike Shop SRL\",\n \"is_company\": true\n },\n \"shipping_address\": {\n \"ready\": true,\n \"reason\": null,\n \"message\": null,\n \"default_address\": {\n \"id\": 4812,\n \"street\": \"Bulevardul Decebal 14\",\n \"city\": \"Craiova\",\n \"county\": \"Dolj\",\n \"postal_code\": \"200001\",\n \"country_code\": \"RO\"\n },\n \"details_url\": \"/v1/addresses\"\n },\n \"rate_limits\": {\n \"per_minute\": 60,\n \"per_day\": 5000\n }\n}" } ] } ] }, { "name": "Invoices", "item": [ { "name": "Fee invoices issued to you · GET /v1/invoices", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/invoices?limit=50&cursor=&issued_from=2026-09-01T00:00:00Z&issued_to=2026-09-30T23:59:59Z", "host": [ "{{base_url}}" ], "path": [ "v1", "invoices" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "issued_from", "value": "2026-09-01T00:00:00Z", "description": "Issued on or after", "disabled": false }, { "key": "issued_to", "value": "2026-09-30T23:59:59Z", "description": "Issued on or before", "disabled": false } ] }, "description": "When your company absorbs the platform commission or the delivery, the buyer is not charged it — Biklo withholds it at payout and invoices you. These are those invoices. One covers SEVERAL orders, because liabilities are raised per order and invoiced in batches at settlement. `written_off_amount` is what Biklo gave up when the absorbed fees exceeded the order itself; you were never charged it, and it is on the document because it happened. `is_sandbox` marks a generated document with an SBX_ series, stamped NOT A FISCAL DOCUMENT.\n\nRequired scope: `wallet.read`." }, "response": [ { "name": "Fee invoices issued to you — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/invoices?limit=50&cursor=&issued_from=2026-09-01T00:00:00Z&issued_to=2026-09-30T23:59:59Z", "host": [ "{{base_url}}" ], "path": [ "v1", "invoices" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "issued_from", "value": "2026-09-01T00:00:00Z", "description": "Issued on or after", "disabled": false }, { "key": "issued_to", "value": "2026-09-30T23:59:59Z", "description": "Issued on or before", "disabled": false } ] }, "description": "When your company absorbs the platform commission or the delivery, the buyer is not charged it — Biklo withholds it at payout and invoices you. These are those invoices. One covers SEVERAL orders, because liabilities are raised per order and invoiced in batches at settlement. `written_off_amount` is what Biklo gave up when the absorbed fees exceeded the order itself; you were never charged it, and it is on the document because it happened. `is_sandbox` marks a generated document with an SBX_ series, stamped NOT A FISCAL DOCUMENT.\n\nRequired scope: `wallet.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": \"RO_BK_COM/0524\",\n \"series\": \"RO_BK_COM\",\n \"number\": \"0524\",\n \"currency\": \"RON\",\n \"total_amount\": 3950,\n \"platform_fee_amount\": 2100,\n \"shipping_fee_amount\": 1850,\n \"written_off_amount\": 350,\n \"orders_count\": 2,\n \"issued_at\": \"2026-09-12T08:10:59Z\",\n \"pdf_url\": \"/v1/invoices/0524/pdf?series=RO_BK_COM\",\n \"is_sandbox\": false\n }\n ]\n}" } ] }, { "name": "One invoice, with the orders behind it · GET /v1/invoices/{number}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/invoices/:number?series=RO_BK_COM", "host": [ "{{base_url}}" ], "path": [ "v1", "invoices", ":number" ], "query": [ { "key": "series", "value": "RO_BK_COM", "description": "Required when the number is ambiguous", "disabled": false } ] }, "description": "Pass `series` when a number could exist in more than one — a number is only unique within its series. `lines` breaks the invoice down per order, with what was owed, what was actually charged, and what was written off.\n\nRequired scope: `wallet.read`." }, "response": [ { "name": "One invoice, with the orders behind it — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/invoices/:number?series=RO_BK_COM", "host": [ "{{base_url}}" ], "path": [ "v1", "invoices", ":number" ], "query": [ { "key": "series", "value": "RO_BK_COM", "description": "Required when the number is ambiguous", "disabled": false } ] }, "description": "Pass `series` when a number could exist in more than one — a number is only unique within its series. `lines` breaks the invoice down per order, with what was owed, what was actually charged, and what was written off.\n\nRequired scope: `wallet.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"RO_BK_COM/0524\",\n \"series\": \"RO_BK_COM\",\n \"number\": \"0524\",\n \"currency\": \"RON\",\n \"total_amount\": 3950,\n \"platform_fee_amount\": 2100,\n \"shipping_fee_amount\": 1850,\n \"written_off_amount\": 350,\n \"orders_count\": 2,\n \"issued_at\": \"2026-09-12T08:10:59Z\",\n \"pdf_url\": \"/v1/invoices/0524/pdf?series=RO_BK_COM\",\n \"is_sandbox\": false,\n \"lines\": [\n {\n \"id\": 15,\n \"order_id\": 721,\n \"currency\": \"RON\",\n \"owed_amount\": 3050,\n \"charged_amount\": 3050,\n \"written_off_amount\": 0,\n \"platform_fee_amount\": 1800,\n \"shipping_fee_amount\": 1250,\n \"status\": \"settled\",\n \"settled_at\": \"2026-09-12T08:09:40Z\",\n \"invoice\": {\n \"series\": \"RO_BK_COM\",\n \"number\": \"0524\",\n \"pdf_url\": \"/v1/invoices/0524/pdf?series=RO_BK_COM\"\n }\n }\n ]\n }\n}" } ] }, { "name": "Download the invoice · GET /v1/invoices/{number}/pdf", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/invoices/:number/pdf?series=RO_BK_COM", "host": [ "{{base_url}}" ], "path": [ "v1", "invoices", ":number", "pdf" ], "query": [ { "key": "series", "value": "RO_BK_COM", "description": "Required when the number is ambiguous", "disabled": false } ] }, "description": "Raw PDF bytes, not JSON — an accounting system files this. Proxied through us rather than linked directly, so ownership is checked before anything is served.\n\nRequired scope: `wallet.read`." }, "response": [ { "name": "Download the invoice — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/invoices/:number/pdf?series=RO_BK_COM", "host": [ "{{base_url}}" ], "path": [ "v1", "invoices", ":number", "pdf" ], "query": [ { "key": "series", "value": "RO_BK_COM", "description": "Required when the number is ambiguous", "disabled": false } ] }, "description": "Raw PDF bytes, not JSON — an accounting system files this. Proxied through us rather than linked directly, so ownership is checked before anything is served.\n\nRequired scope: `wallet.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] } ] }, { "name": "Locations", "item": [ { "name": "Address validation rules · GET /v1/geo/address-rules", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/address-rules?country=RO", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "address-rules" ], "query": [ { "key": "country", "value": "RO", "description": "ISO country code — required", "disabled": false } ] }, "description": "What we enforce when an address is saved, published so you can validate before sending and show your own users a useful message instead of a rejected order.\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "Address validation rules — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/address-rules?country=RO", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "address-rules" ], "query": [ { "key": "country", "value": "RO", "description": "ISO country code — required", "disabled": false } ] }, "description": "What we enforce when an address is saved, published so you can validate before sending and show your own users a useful message instead of a rejected order.\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"country_code\": \"RO\",\n \"street\": {\n \"min_length\": 5,\n \"max_length\": 50,\n \"must_contain_digit\": true\n },\n \"postal_code\": {\n \"pattern\": \"/^\\\\\\\\d{6}$/\",\n \"example\": \"500123\",\n \"validated_by_county_prefix\": true\n },\n \"required_fields\": [\n \"country_code\",\n \"county_id\",\n \"city_id\",\n \"address\",\n \"postal_code\"\n ]\n}" } ] }, { "name": "Search cities · GET /v1/geo/cities", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/cities?country=RO&county_id=&q=craio&limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "cities" ], "query": [ { "key": "country", "value": "RO", "description": "ISO country code", "disabled": false }, { "key": "county_id", "value": "", "description": "Restrict to one county", "disabled": true }, { "key": "q", "value": "craio", "description": "Name prefix, either script", "disabled": false }, { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor from the previous page", "disabled": true } ] }, "description": "Cursor-paginated and always filtered — the table holds 727k rows, so an unfiltered request is refused. Search covers both the local script and the latin form: `q=Sofia` finds `София`.\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "Search cities — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/cities?country=RO&county_id=&q=craio&limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "cities" ], "query": [ { "key": "country", "value": "RO", "description": "ISO country code", "disabled": false }, { "key": "county_id", "value": "", "description": "Restrict to one county", "disabled": true }, { "key": "q", "value": "craio", "description": "Name prefix, either script", "disabled": false }, { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor from the previous page", "disabled": true } ] }, "description": "Cursor-paginated and always filtered — the table holds 727k rows, so an unfiltered request is refused. Search covers both the local script and the latin form: `q=Sofia` finds `София`.\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": 1,\n \"name\": \"Craiova\",\n \"latin_name\": \"Craiova\",\n \"county\": {\n \"id\": 1,\n \"name\": \"Dolj\",\n \"code\": \"DJ\"\n },\n \"latitude\": 44.33,\n \"longitude\": 23.82,\n \"is_capital\": false\n }\n ]\n}" } ] }, { "name": "One city, with postal codes · GET /v1/geo/cities/{id}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/cities/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "cities", ":id" ], "query": [] }, "description": "The postal codes are SUGGESTIONS for autofill. A code missing from this list is not invalid — roughly 7.5% of real codes are absent from our source, so never reject on absence.\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "One city, with postal codes — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/cities/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "cities", ":id" ], "query": [] }, "description": "The postal codes are SUGGESTIONS for autofill. A code missing from this list is not invalid — roughly 7.5% of real codes are absent from our source, so never reject on absence.\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 1,\n \"name\": \"Craiova\",\n \"county\": {\n \"id\": 1,\n \"name\": \"Dolj\",\n \"code\": \"DJ\"\n },\n \"country\": {\n \"code\": \"RO\",\n \"name\": \"Romania\"\n },\n \"postal_codes\": [\n \"200008\",\n \"200009\",\n \"200010\"\n ]\n}" } ] }, { "name": "Counties of a country · GET /v1/geo/counties", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/counties?country=RO", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "counties" ], "query": [ { "key": "country", "value": "RO", "description": "ISO country code — required", "disabled": false } ] }, "description": "The second level of every address. `postal_prefixes` lists the code prefixes valid for that county where we enforce the rule (Romania today).\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "Counties of a country — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/counties?country=RO", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "counties" ], "query": [ { "key": "country", "value": "RO", "description": "ISO country code — required", "disabled": false } ] }, "description": "The second level of every address. `postal_prefixes` lists the code prefixes valid for that county where we enforce the rule (Romania today).\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"country\": \"RO\",\n \"count\": 42,\n \"data\": [\n {\n \"id\": 1,\n \"code\": \"DJ\",\n \"name\": \"Dolj\",\n \"latin_name\": \"Dolj\",\n \"country_code\": \"RO\",\n \"postal_prefixes\": [\n \"20\"\n ]\n }\n ]\n}" } ] }, { "name": "Countries (address taxonomy) · GET /v1/geo/countries", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/countries?all=", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "countries" ], "query": [ { "key": "all", "value": "", "description": "1 to include countries we do not sell in", "disabled": true } ] }, "description": "Countries for building an address. By default only the ones we sell in; pass `all=1` for every country we hold.\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "Countries (address taxonomy) — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/countries?all=", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "countries" ], "query": [ { "key": "all", "value": "", "description": "1 to include countries we do not sell in", "disabled": true } ] }, "description": "Countries for building an address. By default only the ones we sell in; pass `all=1` for every country we hold.\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 32,\n \"data\": [\n {\n \"id\": 190,\n \"code\": \"RO\",\n \"name\": \"Romania\",\n \"currency\": \"RON\",\n \"phone_prefix\": \"40\",\n \"is_active\": true\n }\n ]\n}" } ] }, { "name": "Sub-county areas · GET /v1/geo/subdivisions", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/subdivisions?county_id=1&q=&level=&limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "subdivisions" ], "query": [ { "key": "county_id", "value": "1", "description": "Required unless q is given", "disabled": false }, { "key": "q", "value": "", "description": "Name prefix", "disabled": true }, { "key": "level", "value": "", "description": "Subdivision depth", "disabled": true }, { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true } ] }, "description": "Sectors, districts and municipalities inside a county — what couriers often need for large cities.\n\nRequired scope: `catalog.read`." }, "response": [ { "name": "Sub-county areas — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/geo/subdivisions?county_id=1&q=&level=&limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "geo", "subdivisions" ], "query": [ { "key": "county_id", "value": "1", "description": "Required unless q is given", "disabled": false }, { "key": "q", "value": "", "description": "Name prefix", "disabled": true }, { "key": "level", "value": "", "description": "Subdivision depth", "disabled": true }, { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true } ] }, "description": "Sectors, districts and municipalities inside a county — what couriers often need for large cities.\n\nRequired scope: `catalog.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": 12,\n \"county_id\": 39,\n \"name\": \"Sectorul 3\",\n \"latin_name\": \"Sectorul 3\",\n \"level\": 1,\n \"parent_id\": null\n }\n ]\n}" } ] } ] }, { "name": "Notifications", "item": [ { "name": "Emails and SMS sent about your orders · GET /v1/notifications", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/notifications?limit=50&cursor=&channel=mail&status=suppressed&order_id=721&template=email_shipping_sent", "host": [ "{{base_url}}" ], "path": [ "v1", "notifications" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "channel", "value": "mail", "description": "mail or sms", "disabled": false }, { "key": "status", "value": "suppressed", "description": "sent, failed or suppressed", "disabled": false }, { "key": "order_id", "value": "721", "description": "Only messages about one order", "disabled": false }, { "key": "template", "value": "email_shipping_sent", "description": "Filter by template", "disabled": false } ] }, "description": "Every message the platform sent about one of YOUR orders — scoped by seller, not by recipient, because most of this mail goes to buyers. In the sandbox nothing is delivered, so every row is `suppressed`: composed in full and deliberately not sent. This is the only evidence a test order produced a notification at all. Subscribe to the `notification.sent` webhook rather than polling.\n\nRequired scope: `orders.read`." }, "response": [ { "name": "Emails and SMS sent about your orders — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/notifications?limit=50&cursor=&channel=mail&status=suppressed&order_id=721&template=email_shipping_sent", "host": [ "{{base_url}}" ], "path": [ "v1", "notifications" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "channel", "value": "mail", "description": "mail or sms", "disabled": false }, { "key": "status", "value": "suppressed", "description": "sent, failed or suppressed", "disabled": false }, { "key": "order_id", "value": "721", "description": "Only messages about one order", "disabled": false }, { "key": "template", "value": "email_shipping_sent", "description": "Filter by template", "disabled": false } ] }, "description": "Every message the platform sent about one of YOUR orders — scoped by seller, not by recipient, because most of this mail goes to buyers. In the sandbox nothing is delivered, so every row is `suppressed`: composed in full and deliberately not sent. This is the only evidence a test order produced a notification at all. Subscribe to the `notification.sent` webhook rather than polling.\n\nRequired scope: `orders.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": 7,\n \"channel\": \"mail\",\n \"status\": \"suppressed\",\n \"order_id\": 721,\n \"template\": \"email_shipping_sent\",\n \"subject\": \"Comanda ta a fost expediata\",\n \"preview\": \"AWB 123456\",\n \"created_at\": \"2026-09-12T07:58:14Z\"\n }\n ]\n}" } ] }, { "name": "One notification, with its content · GET /v1/notifications/{id}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/notifications/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "notifications", ":id" ], "query": [] }, "description": "Adds the recipient and the rendered body. `body_available` is false in production, where only metadata is kept — a rendered order email carries the buyer's name, address and phone. The sandbox has no real buyers, so it keeps everything.\n\nRequired scope: `orders.read`." }, "response": [ { "name": "One notification, with its content — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/notifications/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "notifications", ":id" ], "query": [] }, "description": "Adds the recipient and the rendered body. `body_available` is false in production, where only metadata is kept — a rendered order email carries the buyer's name, address and phone. The sandbox has no real buyers, so it keeps everything.\n\nRequired scope: `orders.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": 7,\n \"channel\": \"mail\",\n \"status\": \"suppressed\",\n \"order_id\": 721,\n \"template\": \"email_shipping_sent\",\n \"subject\": \"Comanda ta a fost expediata\",\n \"recipient\": \"buyer@example.com\",\n \"driver\": \"mailing-service\",\n \"body\": \"

AWB 123456

\",\n \"body_available\": true,\n \"created_at\": \"2026-09-12T07:58:14Z\"\n }\n}" } ] } ] }, { "name": "Orders", "item": [ { "name": "List orders · GET /v1/orders", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders?status=&updated_since=&created_from=&created_to=&limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "orders" ], "query": [ { "key": "status", "value": "", "description": "pending | accepted | rejected | ship_to_courier | picked_up | in_delivery | delivered | confirmed | returned | cancelled | expired | lost | not_confirmed", "disabled": true }, { "key": "updated_since", "value": "", "description": "ISO 8601", "disabled": true }, { "key": "created_from", "value": "", "description": " ISO 8601", "disabled": true }, { "key": "created_to", "value": "", "description": "ISO 8601", "disabled": true }, { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true } ] }, "description": "Orders placed with you. Lines carry your own external_id and sku so you can match them to your catalog without a lookup.\n\nRequired scope: `orders.read`." }, "response": [ { "name": "List orders — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders?status=&updated_since=&created_from=&created_to=&limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "orders" ], "query": [ { "key": "status", "value": "", "description": "pending | accepted | rejected | ship_to_courier | picked_up | in_delivery | delivered | confirmed | returned | cancelled | expired | lost | not_confirmed", "disabled": true }, { "key": "updated_since", "value": "", "description": "ISO 8601", "disabled": true }, { "key": "created_from", "value": "", "description": " ISO 8601", "disabled": true }, { "key": "created_to", "value": "", "description": "ISO 8601", "disabled": true }, { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true } ] }, "description": "Orders placed with you. Lines carry your own external_id and sku so you can match them to your catalog without a lookup.\n\nRequired scope: `orders.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": 711,\n \"reference\": \"SBXORD-SJP6NHXY\",\n \"status\": \"pending\",\n \"can_accept\": true,\n \"has_awb\": false,\n \"total\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n },\n \"refunded\": {\n \"amount\": 0,\n \"currency\": \"RON\"\n },\n \"items\": [\n {\n \"id\": 1123,\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"quantity\": 2,\n \"quantity_ordered\": 2,\n \"quantity_short\": 0,\n \"unit_price\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"total_price\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n }\n }\n ],\n \"awb\": null,\n \"is_dropshipping\": false,\n \"delivered_at\": null,\n \"created_at\": \"2026-09-11T09:20:14Z\",\n \"updated_at\": \"2026-09-11T09:20:14Z\"\n }\n ]\n}" } ] }, { "name": "One order · GET /v1/orders/{id}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id" ], "query": [] }, "description": "Adds the delivery details you need to ship, the fee breakdown and the courier.\n\nRequired scope: `orders.read`." }, "response": [ { "name": "One order — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id" ], "query": [] }, "description": "Adds the delivery details you need to ship, the fee breakdown and the courier.\n\nRequired scope: `orders.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 711,\n \"reference\": \"SBXORD-SJP6NHXY\",\n \"status\": \"accepted\",\n \"can_accept\": false,\n \"has_awb\": true,\n \"total\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n },\n \"refunded\": {\n \"amount\": 0,\n \"currency\": \"RON\"\n },\n \"items\": [\n {\n \"id\": 1123,\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"quantity\": 2,\n \"quantity_ordered\": 2,\n \"quantity_short\": 0,\n \"unit_price\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"total_price\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n }\n }\n ],\n \"awb\": {\n \"number\": \"SBX0000000711\",\n \"tracking_url\": \"https://sandbox-api.biklo.com/track/SBX0000000711\"\n },\n \"is_dropshipping\": false,\n \"created_at\": \"2026-09-11T09:20:14Z\",\n \"updated_at\": \"2026-09-11T10:02:47Z\",\n \"accepted_at\": \"2026-09-11T10:02:47Z\",\n \"delivered_at\": null,\n \"expires_at\": \"2026-09-13T09:20:14Z\",\n \"notes_from_buyer\": \"Please call before delivery.\",\n \"courier_id\": 1,\n \"seller_invoice\": null,\n \"fees\": {\n \"platform_fee\": 17990,\n \"shipping\": 2500,\n \"currency\": \"RON\"\n },\n \"delivery\": {\n \"recipient\": \"John Doe\",\n \"phone\": \"07xxxxxxxx\",\n \"city\": \"Craiova\",\n \"county\": \"Dolj\",\n \"postcode\": \"200000\",\n \"country\": \"RO\",\n \"is_locker\": false\n },\n \"refunds\": [],\n \"parcels\": [\n {\n \"id\": 4012,\n \"sequence_no\": 1,\n \"weight_kg\": 2.4,\n \"length_cm\": 40,\n \"width_cm\": 30,\n \"height_cm\": 20,\n \"is_seller_declared\": true,\n \"items\": [\n {\n \"order_item_id\": 1123,\n \"quantity\": 2\n }\n ]\n }\n ]\n}" } ] }, { "name": "The customer behind one order · GET /v1/orders/{id}/customer", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/customer", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "customer" ], "query": [] }, "description": "The endpoint to reach for when you are about to raise an invoice: you are holding an order id and you need the buyer AS THEY WERE FOR THAT SALE. A customer who has moved has two orders at two addresses, and each invoice must carry its own — `GET /v1/customers/{id}` gives you their latest, this gives you that order's. An order with no buyer account on it is `customer_not_found` (404).\n\nRequired scope: `customers.read`." }, "response": [ { "name": "The customer behind one order — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/customer", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "customer" ], "query": [] }, "description": "The endpoint to reach for when you are about to raise an invoice: you are holding an order id and you need the buyer AS THEY WERE FOR THAT SALE. A customer who has moved has two orders at two addresses, and each invoice must carry its own — `GET /v1/customers/{id}` gives you their latest, this gives you that order's. An order with no buyer account on it is `customer_not_found` (404).\n\nRequired scope: `customers.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 9000001,\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+40700000000\",\n \"billing\": {\n \"address_line\": \"Str. Exemplu 12\",\n \"city\": \"Brasov\",\n \"county\": \"Brasov\",\n \"postal_code\": \"500002\",\n \"country_code\": \"RO\",\n \"country\": \"România\",\n \"is_company\": true,\n \"company\": {\n \"name\": \"Example Bike Shop SRL\",\n \"vat_code\": \"RO12345678\",\n \"registration_no\": \"J16/123/2020\"\n },\n \"is_live\": true,\n \"delivered_to_locker\": false\n }\n}" } ] }, { "name": "Download the label · GET /v1/orders/{id}/label", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/label?format=pdf&size=a6", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "label" ], "query": [ { "key": "format", "value": "pdf", "description": "pdf or zpl", "disabled": false }, { "key": "size", "value": "a6", "description": "PDF page size: a6, a5, a4 or original. Default: the seller's saved choice, else a6.", "disabled": false } ] }, "description": "Returns the label BYTES, not JSON — send it straight to a printer. ZPL is what most warehouse printers want.\n\nPDF labels come in a page size: `?size=a6` (105 × 148 mm, label printer), `a5`, `a4`, or `original` (the courier's own PDF, usually an A4 sheet with the label printed twice). Without `size` you get the size the seller chose in their Biklo settings, and **A6** if they never chose. Each distinct label gets its own portrait page; a duplicate copy is dropped, every parcel of a multi-parcel order is kept. A4/A5 print at real size, A6 fills the page. The `X-Label-Size` response header says what you received — `original` while Biklo has label formatting switched off. `size` does not apply to ZPL.\n\nRequired scope: `orders.read`." }, "response": [ { "name": "Download the label — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/label?format=pdf&size=a6", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "label" ], "query": [ { "key": "format", "value": "pdf", "description": "pdf or zpl", "disabled": false }, { "key": "size", "value": "a6", "description": "PDF page size: a6, a5, a4 or original. Default: the seller's saved choice, else a6.", "disabled": false } ] }, "description": "Returns the label BYTES, not JSON — send it straight to a printer. ZPL is what most warehouse printers want.\n\nPDF labels come in a page size: `?size=a6` (105 × 148 mm, label printer), `a5`, `a4`, or `original` (the courier's own PDF, usually an A4 sheet with the label printed twice). Without `size` you get the size the seller chose in their Biklo settings, and **A6** if they never chose. Each distinct label gets its own portrait page; a duplicate copy is dropped, every parcel of a multi-parcel order is kept. A4/A5 print at real size, A6 fills the page. The `X-Label-Size` response header says what you received — `original` while Biklo has label formatting switched off. `size` does not apply to ZPL.\n\nRequired scope: `orders.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Tracking events · GET /v1/orders/{id}/tracking", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/tracking", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "tracking" ], "query": [] }, "description": "The courier's own history where we have it; before an AWB exists it falls back to the order's own milestones so you always have something to render.\n\nRequired scope: `orders.read`." }, "response": [ { "name": "Tracking events — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/tracking", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "tracking" ], "query": [] }, "description": "The courier's own history where we have it; before an AWB exists it falls back to the order's own milestones so you always have something to render.\n\nRequired scope: `orders.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"order_id\": 711,\n \"status\": \"Livrat\",\n \"internal_status\": \"accepted\",\n \"awb\": {\n \"number\": \"SBX0000007112\",\n \"tracking_url\": \"https://sandbox-api.biklo.com/track/SBX0000007112\"\n },\n \"events\": [\n {\n \"status\": \"accepted\",\n \"at\": \"2026-09-09T19:40:19Z\",\n \"location\": null,\n \"source\": \"order\",\n \"is_final\": false\n },\n {\n \"status\": \"Livrat\",\n \"at\": \"2026-09-11T14:22:05Z\",\n \"location\": \"Craiova\",\n \"source\": \"courier\",\n \"is_final\": true\n }\n ]\n}" } ] }, { "name": "List returns · GET /v1/returns", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/returns?limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "returns" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true } ] }, "description": "Returns buyers have raised against your orders.\n\nRequired scope: `orders.read`." }, "response": [ { "name": "List returns — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/returns?limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "returns" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true } ] }, "description": "Returns buyers have raised against your orders.\n\nRequired scope: `orders.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": 8,\n \"order_id\": 711,\n \"return_order_id\": 742,\n \"reference\": \"SBXORD-SJP6NHXY\",\n \"reason\": \"Wrong size delivered\",\n \"order_status\": \"delivered\",\n \"requested_at\": \"2026-09-09T19:45:00Z\",\n \"inspection\": {\n \"status\": \"awaiting_seller\",\n \"delivered_at\": \"2026-09-12T09:10:00Z\",\n \"deadline_at\": \"2026-09-14T09:10:00Z\",\n \"refund\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"refunded\": null,\n \"decided_at\": null,\n \"decided_by\": null,\n \"can_accept\": true,\n \"can_reject\": true\n },\n \"items\": [\n {\n \"id\": 1123,\n \"product_id\": 237224,\n \"quantity\": 1,\n \"total_price\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"return_status\": \"requested\"\n }\n ]\n }\n ]\n}" } ] }, { "name": "Accept an order · POST /v1/orders/{id}/accept", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/accept", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "accept" ], "query": [] }, "description": "Only a pending order can be accepted; anything else returns 409 with its current status. Accepting BOOKS THE COURIER, exactly as Accept does in the seller dashboard: the response carries the AWB (`awb.number`, `awb.tracking_url`), the label is ready at GET /v1/orders/{id}/label, tracking starts, and the buyer gets the usual emails and SMS. If the courier cannot be booked the order stays pending and nothing changed — fix the reason (`courier_required`, `buyer_phone_missing`, `awb_generation_failed` 502) and call again. A face-to-face order is accepted without a courier. This is also where you declare how the order is PACKED. Send nothing and one box per order line is assumed. Send `parcels` to combine lines into fewer boxes or split a line's pieces across boxes — the courier is quoted per parcel. Never more boxes than pieces. Reference lines by the `id` on each item from GET /v1/orders/{id}, and give dimensions in cm and kg like everywhere else. SHORT SHIPMENT: if you have fewer pieces of a line than were ordered, send `items` with how many you ship. The courier is booked for those pieces, and only once it returned an AWB are the lines reduced and the buyer refunded the product price of the missing pieces (delivery and fees are not refunded); a failed booking changes nothing. The order then carries `quantity_ordered` / `quantity_short` per line and the refund, `order.items_changed` is sent, and the listing is set to stock 0.\n\nRequired scope: `orders.write`.", "body": { "mode": "raw", "raw": "{\n \"items\": [\n {\n \"id\": 1123,\n \"quantity\": 1\n }\n ],\n \"parcels\": [\n {\n \"items\": [\n {\n \"shipping_item_id\": 1123,\n \"quantity\": 2\n },\n {\n \"shipping_item_id\": 1124,\n \"quantity\": 1\n }\n ],\n \"weight_kg\": 2.4,\n \"length_cm\": 40,\n \"width_cm\": 30,\n \"height_cm\": 20\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Accept an order — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/accept", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "accept" ], "query": [] }, "description": "Only a pending order can be accepted; anything else returns 409 with its current status. Accepting BOOKS THE COURIER, exactly as Accept does in the seller dashboard: the response carries the AWB (`awb.number`, `awb.tracking_url`), the label is ready at GET /v1/orders/{id}/label, tracking starts, and the buyer gets the usual emails and SMS. If the courier cannot be booked the order stays pending and nothing changed — fix the reason (`courier_required`, `buyer_phone_missing`, `awb_generation_failed` 502) and call again. A face-to-face order is accepted without a courier. This is also where you declare how the order is PACKED. Send nothing and one box per order line is assumed. Send `parcels` to combine lines into fewer boxes or split a line's pieces across boxes — the courier is quoted per parcel. Never more boxes than pieces. Reference lines by the `id` on each item from GET /v1/orders/{id}, and give dimensions in cm and kg like everywhere else. SHORT SHIPMENT: if you have fewer pieces of a line than were ordered, send `items` with how many you ship. The courier is booked for those pieces, and only once it returned an AWB are the lines reduced and the buyer refunded the product price of the missing pieces (delivery and fees are not refunded); a failed booking changes nothing. The order then carries `quantity_ordered` / `quantity_short` per line and the refund, `order.items_changed` is sent, and the listing is set to stock 0.\n\nRequired scope: `orders.write`.", "body": { "mode": "raw", "raw": "{\n \"items\": [\n {\n \"id\": 1123,\n \"quantity\": 1\n }\n ],\n \"parcels\": [\n {\n \"items\": [\n {\n \"shipping_item_id\": 1123,\n \"quantity\": 2\n },\n {\n \"shipping_item_id\": 1124,\n \"quantity\": 1\n }\n ],\n \"weight_kg\": 2.4,\n \"length_cm\": 40,\n \"width_cm\": 30,\n \"height_cm\": 20\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 711,\n \"reference\": \"SBXORD-SJP6NHXY\",\n \"status\": \"accepted\",\n \"can_accept\": false,\n \"has_awb\": true,\n \"total\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n },\n \"refunded\": {\n \"amount\": 0,\n \"currency\": \"RON\"\n },\n \"items\": [\n {\n \"id\": 1123,\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"quantity\": 2,\n \"quantity_ordered\": 2,\n \"quantity_short\": 0,\n \"unit_price\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"total_price\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n }\n }\n ],\n \"awb\": {\n \"number\": \"SBX0000000711\",\n \"tracking_url\": \"https://sandbox-api.biklo.com/track/SBX0000000711\"\n },\n \"is_dropshipping\": false,\n \"created_at\": \"2026-09-11T09:20:14Z\",\n \"updated_at\": \"2026-09-11T10:02:47Z\",\n \"accepted_at\": \"2026-09-11T10:02:47Z\",\n \"delivered_at\": null,\n \"expires_at\": \"2026-09-13T09:20:14Z\",\n \"notes_from_buyer\": \"Please call before delivery.\",\n \"courier_id\": 1,\n \"seller_invoice\": null,\n \"fees\": {\n \"platform_fee\": 17990,\n \"shipping\": 2500,\n \"currency\": \"RON\"\n },\n \"delivery\": {\n \"recipient\": \"John Doe\",\n \"phone\": \"07xxxxxxxx\",\n \"city\": \"Craiova\",\n \"county\": \"Dolj\",\n \"postcode\": \"200000\",\n \"country\": \"RO\",\n \"is_locker\": false\n },\n \"refunds\": [],\n \"parcels\": [\n {\n \"id\": 4012,\n \"sequence_no\": 1,\n \"weight_kg\": 2.4,\n \"length_cm\": 40,\n \"width_cm\": 30,\n \"height_cm\": 20,\n \"is_seller_declared\": true,\n \"items\": [\n {\n \"order_item_id\": 1123,\n \"quantity\": 2\n }\n ]\n }\n ]\n}" } ] }, { "name": "Request a waybill · POST /v1/orders/{id}/awb", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/awb", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "awb" ], "query": [] }, "description": "Accepting an order already books its courier, so this returns that AWB (`already_existed: true`). It books one only for an order accepted before accept did so — and it is idempotent: never a second shipment for the same order.\n\nRequired scope: `orders.write`.", "body": { "mode": "raw", "raw": "[]", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Request a waybill — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/awb", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "awb" ], "query": [] }, "description": "Accepting an order already books its courier, so this returns that AWB (`already_existed: true`). It books one only for an order accepted before accept did so — and it is idempotent: never a second shipment for the same order.\n\nRequired scope: `orders.write`.", "body": { "mode": "raw", "raw": "[]", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"awb\": {\n \"number\": \"SBX0000007112\",\n \"tracking_url\": \"https://.../sandbox/tracking/SBX0000007112\"\n },\n \"already_existed\": false\n}" } ] }, { "name": "Confirm handover (deprecated) · POST /v1/orders/{id}/confirm-shipped", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/confirm-shipped", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "confirm-shipped" ], "query": [] }, "description": "**Deprecated — you do not need to call this.** Accepting the order books the courier, and the parcel's progress comes from the courier itself (`GET /v1/orders/{id}/tracking`). The endpoint still answers `200` with the order, unchanged, so existing integrations keep working; it no longer changes anything. Remove the call when convenient.\n\nRequired scope: `orders.write`." }, "response": [ { "name": "Confirm handover (deprecated) — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/confirm-shipped", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "confirm-shipped" ], "query": [] }, "description": "**Deprecated — you do not need to call this.** Accepting the order books the courier, and the parcel's progress comes from the courier itself (`GET /v1/orders/{id}/tracking`). The endpoint still answers `200` with the order, unchanged, so existing integrations keep working; it no longer changes anything. Remove the call when convenient.\n\nRequired scope: `orders.write`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 711,\n \"reference\": \"SBXORD-SJP6NHXY\",\n \"status\": \"accepted\",\n \"can_accept\": false,\n \"has_awb\": true,\n \"total\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n },\n \"refunded\": {\n \"amount\": 0,\n \"currency\": \"RON\"\n },\n \"items\": [\n {\n \"id\": 1123,\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"quantity\": 2,\n \"quantity_ordered\": 2,\n \"quantity_short\": 0,\n \"unit_price\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"total_price\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n }\n }\n ],\n \"awb\": {\n \"number\": \"SBX0000000711\",\n \"tracking_url\": \"https://sandbox-api.biklo.com/track/SBX0000000711\"\n },\n \"is_dropshipping\": false,\n \"created_at\": \"2026-09-11T09:20:14Z\",\n \"updated_at\": \"2026-09-11T10:02:47Z\",\n \"accepted_at\": \"2026-09-11T10:02:47Z\",\n \"delivered_at\": null,\n \"expires_at\": \"2026-09-13T09:20:14Z\",\n \"notes_from_buyer\": \"Please call before delivery.\",\n \"courier_id\": 1,\n \"seller_invoice\": null,\n \"fees\": {\n \"platform_fee\": 17990,\n \"shipping\": 2500,\n \"currency\": \"RON\"\n },\n \"delivery\": {\n \"recipient\": \"John Doe\",\n \"phone\": \"07xxxxxxxx\",\n \"city\": \"Craiova\",\n \"county\": \"Dolj\",\n \"postcode\": \"200000\",\n \"country\": \"RO\",\n \"is_locker\": false\n },\n \"refunds\": [],\n \"parcels\": [\n {\n \"id\": 4012,\n \"sequence_no\": 1,\n \"weight_kg\": 2.4,\n \"length_cm\": 40,\n \"width_cm\": 30,\n \"height_cm\": 20,\n \"is_seller_declared\": true,\n \"items\": [\n {\n \"order_item_id\": 1123,\n \"quantity\": 2\n }\n ]\n }\n ]\n}" } ] }, { "name": "Upload your invoice · POST /v1/orders/{id}/invoice", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/invoice", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "invoice" ], "query": [] }, "description": "YOUR fiscal invoice for the goods — Biklo does not issue it. Send a multipart `file`, or a `url` we reference without downloading.\n\nRequired scope: `orders.write`.", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://erp.example.com/invoices/FCT-2026-001.pdf\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Upload your invoice — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/invoice", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "invoice" ], "query": [] }, "description": "YOUR fiscal invoice for the goods — Biklo does not issue it. Send a multipart `file`, or a `url` we reference without downloading.\n\nRequired scope: `orders.write`.", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://erp.example.com/invoices/FCT-2026-001.pdf\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"order_id\": 711,\n \"seller_invoice\": \"https://erp.example.com/invoices/FCT-2026-001.pdf\"\n}" } ] }, { "name": "Reject an order · POST /v1/orders/{id}/reject", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/reject", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "reject" ], "query": [] }, "description": "Refunds the buyer for this order. Possible while the order is pending or accepted.\n\nRequired scope: `orders.write`." }, "response": [ { "name": "Reject an order — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/:id/reject", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", ":id", "reject" ], "query": [] }, "description": "Refunds the buyer for this order. Possible while the order is pending or accepted.\n\nRequired scope: `orders.write`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 711,\n \"reference\": \"SBXORD-SJP6NHXY\",\n \"status\": \"rejected\",\n \"can_accept\": false,\n \"has_awb\": true,\n \"total\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n },\n \"refunded\": {\n \"amount\": 0,\n \"currency\": \"RON\"\n },\n \"items\": [\n {\n \"id\": 1123,\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"quantity\": 2,\n \"quantity_ordered\": 2,\n \"quantity_short\": 0,\n \"unit_price\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"total_price\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n }\n }\n ],\n \"awb\": {\n \"number\": \"SBX0000000711\",\n \"tracking_url\": \"https://sandbox-api.biklo.com/track/SBX0000000711\"\n },\n \"is_dropshipping\": false,\n \"created_at\": \"2026-09-11T09:20:14Z\",\n \"updated_at\": \"2026-09-11T10:02:47Z\",\n \"accepted_at\": \"2026-09-11T10:02:47Z\",\n \"delivered_at\": null,\n \"expires_at\": \"2026-09-13T09:20:14Z\",\n \"notes_from_buyer\": \"Please call before delivery.\",\n \"courier_id\": 1,\n \"seller_invoice\": null,\n \"fees\": {\n \"platform_fee\": 17990,\n \"shipping\": 2500,\n \"currency\": \"RON\"\n },\n \"delivery\": {\n \"recipient\": \"John Doe\",\n \"phone\": \"07xxxxxxxx\",\n \"city\": \"Craiova\",\n \"county\": \"Dolj\",\n \"postcode\": \"200000\",\n \"country\": \"RO\",\n \"is_locker\": false\n },\n \"refunds\": [],\n \"parcels\": [\n {\n \"id\": 4012,\n \"sequence_no\": 1,\n \"weight_kg\": 2.4,\n \"length_cm\": 40,\n \"width_cm\": 30,\n \"height_cm\": 20,\n \"is_seller_declared\": true,\n \"items\": [\n {\n \"order_item_id\": 1123,\n \"quantity\": 2\n }\n ]\n }\n ]\n}" } ] }, { "name": "Accept a return · POST /v1/returns/{id}/accept", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/returns/:id/accept", "host": [ "{{base_url}}" ], "path": [ "v1", "returns", ":id", "accept" ], "query": [] }, "description": "Takes the ORDER id. You checked the returned product and it is fine: the buyer is refunded the price of the returned lines from the held money. Only once the return parcel is delivered to you and before `inspection.deadline_at` (`GET /v1/returns`). Refused with 409: `return_not_delivered` (the parcel is not back yet), `return_not_open` (already decided, or the Biklo team decides it now), `inspection_deadline_passed`, `return_decision_failed` (the refund did not go through; nothing changed). On an order paid before Biklo Payments it only marks the order returned. Returns the order.\n\nRequired scope: `orders.write`." }, "response": [ { "name": "Accept a return — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/returns/:id/accept", "host": [ "{{base_url}}" ], "path": [ "v1", "returns", ":id", "accept" ], "query": [] }, "description": "Takes the ORDER id. You checked the returned product and it is fine: the buyer is refunded the price of the returned lines from the held money. Only once the return parcel is delivered to you and before `inspection.deadline_at` (`GET /v1/returns`). Refused with 409: `return_not_delivered` (the parcel is not back yet), `return_not_open` (already decided, or the Biklo team decides it now), `inspection_deadline_passed`, `return_decision_failed` (the refund did not go through; nothing changed). On an order paid before Biklo Payments it only marks the order returned. Returns the order.\n\nRequired scope: `orders.write`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 711,\n \"reference\": \"SBXORD-SJP6NHXY\",\n \"status\": \"returned\",\n \"can_accept\": false,\n \"has_awb\": true,\n \"total\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n },\n \"refunded\": {\n \"amount\": 0,\n \"currency\": \"RON\"\n },\n \"items\": [\n {\n \"id\": 1123,\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"quantity\": 2,\n \"quantity_ordered\": 2,\n \"quantity_short\": 0,\n \"unit_price\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"total_price\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n }\n }\n ],\n \"awb\": {\n \"number\": \"SBX0000000711\",\n \"tracking_url\": \"https://sandbox-api.biklo.com/track/SBX0000000711\"\n },\n \"is_dropshipping\": false,\n \"created_at\": \"2026-09-11T09:20:14Z\",\n \"updated_at\": \"2026-09-11T10:02:47Z\",\n \"accepted_at\": \"2026-09-11T10:02:47Z\",\n \"delivered_at\": null,\n \"expires_at\": \"2026-09-13T09:20:14Z\",\n \"notes_from_buyer\": \"Please call before delivery.\",\n \"courier_id\": 1,\n \"seller_invoice\": null,\n \"fees\": {\n \"platform_fee\": 17990,\n \"shipping\": 2500,\n \"currency\": \"RON\"\n },\n \"delivery\": {\n \"recipient\": \"John Doe\",\n \"phone\": \"07xxxxxxxx\",\n \"city\": \"Craiova\",\n \"county\": \"Dolj\",\n \"postcode\": \"200000\",\n \"country\": \"RO\",\n \"is_locker\": false\n },\n \"refunds\": [],\n \"parcels\": [\n {\n \"id\": 4012,\n \"sequence_no\": 1,\n \"weight_kg\": 2.4,\n \"length_cm\": 40,\n \"width_cm\": 30,\n \"height_cm\": 20,\n \"is_seller_declared\": true,\n \"items\": [\n {\n \"order_item_id\": 1123,\n \"quantity\": 2\n }\n ]\n }\n ]\n}" } ] }, { "name": "Reject a return · POST /v1/returns/{id}/reject", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/returns/:id/reject", "host": [ "{{base_url}}" ], "path": [ "v1", "returns", ":id", "reject" ], "query": [] }, "description": "Takes the ORDER id. The returned product is not what was sent, or it came back damaged: this opens a dispute for the Biklo team, who decide — refund in full, refund part, or no refund. The money stays held meanwhile; you get `return.escalated`, then `return.resolved`. Same timing and the same 409 refusals as accept. Returns the order.\n\nRequired scope: `orders.write`.", "body": { "mode": "raw", "raw": "{\n \"reason\": \"The returned bike has a cracked frame that was not there when we shipped it. Photos sent by email.\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Reject a return — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/returns/:id/reject", "host": [ "{{base_url}}" ], "path": [ "v1", "returns", ":id", "reject" ], "query": [] }, "description": "Takes the ORDER id. The returned product is not what was sent, or it came back damaged: this opens a dispute for the Biklo team, who decide — refund in full, refund part, or no refund. The money stays held meanwhile; you get `return.escalated`, then `return.resolved`. Same timing and the same 409 refusals as accept. Returns the order.\n\nRequired scope: `orders.write`.", "body": { "mode": "raw", "raw": "{\n \"reason\": \"The returned bike has a cracked frame that was not there when we shipped it. Photos sent by email.\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 711,\n \"reference\": \"SBXORD-SJP6NHXY\",\n \"status\": \"returned\",\n \"can_accept\": false,\n \"has_awb\": true,\n \"total\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n },\n \"refunded\": {\n \"amount\": 0,\n \"currency\": \"RON\"\n },\n \"items\": [\n {\n \"id\": 1123,\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"quantity\": 2,\n \"quantity_ordered\": 2,\n \"quantity_short\": 0,\n \"unit_price\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"total_price\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n }\n }\n ],\n \"awb\": {\n \"number\": \"SBX0000000711\",\n \"tracking_url\": \"https://sandbox-api.biklo.com/track/SBX0000000711\"\n },\n \"is_dropshipping\": false,\n \"created_at\": \"2026-09-11T09:20:14Z\",\n \"updated_at\": \"2026-09-11T10:02:47Z\",\n \"accepted_at\": \"2026-09-11T10:02:47Z\",\n \"delivered_at\": null,\n \"expires_at\": \"2026-09-13T09:20:14Z\",\n \"notes_from_buyer\": \"Please call before delivery.\",\n \"courier_id\": 1,\n \"seller_invoice\": null,\n \"fees\": {\n \"platform_fee\": 17990,\n \"shipping\": 2500,\n \"currency\": \"RON\"\n },\n \"delivery\": {\n \"recipient\": \"John Doe\",\n \"phone\": \"07xxxxxxxx\",\n \"city\": \"Craiova\",\n \"county\": \"Dolj\",\n \"postcode\": \"200000\",\n \"country\": \"RO\",\n \"is_locker\": false\n },\n \"refunds\": [],\n \"parcels\": [\n {\n \"id\": 4012,\n \"sequence_no\": 1,\n \"weight_kg\": 2.4,\n \"length_cm\": 40,\n \"width_cm\": 30,\n \"height_cm\": 20,\n \"is_seller_declared\": true,\n \"items\": [\n {\n \"order_item_id\": 1123,\n \"quantity\": 2\n }\n ]\n }\n ]\n}" } ] } ] }, { "name": "Products", "item": [ { "name": "Remove one variant · DELETE /v1/product-groups/{externalGroupId}/products/{productId}", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/product-groups/:externalGroupId/products/:productId", "host": [ "{{base_url}}" ], "path": [ "v1", "product-groups", ":externalGroupId", "products", ":productId" ], "query": [] }, "description": "The group survives while two or more products remain.\n\nRequired scope: `products.write`." }, "response": [ { "name": "Remove one variant — 200", "originalRequest": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/product-groups/:externalGroupId/products/:productId", "host": [ "{{base_url}}" ], "path": [ "v1", "product-groups", ":externalGroupId", "products", ":productId" ], "query": [] }, "description": "The group survives while two or more products remain.\n\nRequired scope: `products.write`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"external_group_id\": \"ERP-1001-GROUP\",\n \"count\": 1\n}" } ] }, { "name": "Delete an image · DELETE /v1/products/{id}/images/{imageId}", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/images/:imageId", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "images", ":imageId" ], "query": [] }, "description": "Removes the row and, for an uploaded file, the file itself.\n\nRequired scope: `products.write`." }, "response": [ { "name": "Delete an image — 200", "originalRequest": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/images/:imageId", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "images", ":imageId" ], "query": [] }, "description": "Removes the row and, for an uploaded file, the file itself.\n\nRequired scope: `products.write`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n }\n ]\n}" } ] }, { "name": "Read a variant group · GET /v1/product-groups/{externalGroupId}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/product-groups/:externalGroupId", "host": [ "{{base_url}}" ], "path": [ "v1", "product-groups", ":externalGroupId" ], "query": [] }, "description": "By your own group id.\n\nRequired scope: `products.read`." }, "response": [ { "name": "Read a variant group — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/product-groups/:externalGroupId", "host": [ "{{base_url}}" ], "path": [ "v1", "product-groups", ":externalGroupId" ], "query": [] }, "description": "By your own group id.\n\nRequired scope: `products.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"external_group_id\": \"ERP-1001-GROUP\",\n \"group_id\": 904,\n \"count\": 2,\n \"variants\": [\n {\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001-S\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"price\": {\n \"amount\": 249900\n },\n \"stock\": 4,\n \"size\": \"S\",\n \"color\": \"Negru\",\n \"gender\": null,\n \"is_representative\": true\n },\n {\n \"product_id\": 237225,\n \"external_id\": \"ERP-1001-M\",\n \"sku\": \"MTB-29-001-M\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"price\": {\n \"amount\": 249900\n },\n \"stock\": 2,\n \"size\": \"M\",\n \"color\": \"Negru\",\n \"gender\": null,\n \"is_representative\": false\n }\n ]\n}" } ] }, { "name": "List your products · GET /v1/products", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products?updated_since=2026-09-01T00:00:00Z&status=active&sku=&external_id=&category_id=&limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "products" ], "query": [ { "key": "updated_since", "value": "2026-09-01T00:00:00Z", "description": "ISO 8601", "disabled": false }, { "key": "status", "value": "active", "description": "active | draft | sold | archived", "disabled": false }, { "key": "sku", "value": "", "description": " Exact match", "disabled": true }, { "key": "external_id", "value": "", "description": "Your own id", "disabled": true }, { "key": "category_id", "value": "", "description": "Master or translated id", "disabled": true }, { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true } ] }, "description": "Your own catalog only, cursor-paginated. Use `updated_since` for incremental sync instead of re-reading everything.\n\nRequired scope: `products.read`." }, "response": [ { "name": "List your products — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products?updated_since=2026-09-01T00:00:00Z&status=active&sku=&external_id=&category_id=&limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "products" ], "query": [ { "key": "updated_since", "value": "2026-09-01T00:00:00Z", "description": "ISO 8601", "disabled": false }, { "key": "status", "value": "active", "description": "active | draft | sold | archived", "disabled": false }, { "key": "sku", "value": "", "description": " Exact match", "disabled": true }, { "key": "external_id", "value": "", "description": "Your own id", "disabled": true }, { "key": "category_id", "value": "", "description": "Master or translated id", "disabled": true }, { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true } ] }, "description": "Your own catalog only, cursor-paginated. Use `updated_since` for incremental sync instead of re-reading everything.\n\nRequired scope: `products.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": \"165987\",\n \"data\": [\n {\n \"id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"gtin\": null,\n \"mpn\": null,\n \"ean\": null,\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition, barely used.\",\n \"category_id\": 4291,\n \"status\": \"active\",\n \"is_reviewed\": true,\n \"price\": {\n \"amount\": 249900,\n \"currency\": \"RON\",\n \"negotiable\": true\n },\n \"stock\": 4,\n \"shipping\": {\n \"ship_with_us\": true,\n \"free_shipping\": false,\n \"shipping_class\": \"bike\",\n \"parcel_tier\": \"large\",\n \"weight_kg\": 14.5,\n \"width_cm\": 80,\n \"height_cm\": 120,\n \"length_cm\": 180\n },\n \"group_id\": null,\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n }\n ],\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226,\n \"value\": null\n }\n ],\n \"created_at\": \"2026-09-01T08:14:22Z\",\n \"updated_at\": \"2026-09-11T16:02:51Z\"\n }\n ]\n}" } ] }, { "name": "Batch status and per-item results · GET /v1/products/batch/{batchId}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/batch/:batchId?failed_only=", "host": [ "{{base_url}}" ], "path": [ "v1", "products", "batch", ":batchId" ], "query": [ { "key": "failed_only", "value": "", "description": "1 to return only the failures", "disabled": true } ] }, "description": "Failures are listed first, because that is what you opened this for. `?failed_only=1` returns just those.\n\nRequired scope: `products.write`." }, "response": [ { "name": "Batch status and per-item results — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/batch/:batchId?failed_only=", "host": [ "{{base_url}}" ], "path": [ "v1", "products", "batch", ":batchId" ], "query": [ { "key": "failed_only", "value": "", "description": "1 to return only the failures", "disabled": true } ] }, "description": "Failures are listed first, because that is what you opened this for. `?failed_only=1` returns just those.\n\nRequired scope: `products.write`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"batch_id\": \"batch_v4lfngtgb6sxqkzwagrqv8c2\",\n \"status\": \"completed\",\n \"total\": 7,\n \"processed\": 7,\n \"succeeded\": 5,\n \"failed\": 2,\n \"created_at\": \"2026-09-11T14:02:10Z\",\n \"completed_at\": \"2026-09-11T14:02:38Z\",\n \"error\": null,\n \"items_shown\": 2,\n \"items\": [\n {\n \"position\": 0,\n \"external_id\": \"ERP-1001\",\n \"status\": \"success\",\n \"product_id\": 237224,\n \"error\": null\n },\n {\n \"position\": 5,\n \"external_id\": \"BATCH-BAD\",\n \"status\": \"failed\",\n \"product_id\": null,\n \"error\": {\n \"code\": \"missing_required_attribute\",\n \"message\": \"The attribute \\\"Brand\\\" is required for this category.\"\n }\n }\n ]\n}" } ] }, { "name": "One product · GET /v1/products/{id}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id?by=", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id" ], "query": [ { "key": "by", "value": "", "description": "Set to external_id to look up by your identifier", "disabled": true } ] }, "description": "By our id, or by your own with `?by=external_id`.\n\nRequired scope: `products.read`." }, "response": [ { "name": "One product — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id?by=", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id" ], "query": [ { "key": "by", "value": "", "description": "Set to external_id to look up by your identifier", "disabled": true } ] }, "description": "By our id, or by your own with `?by=external_id`.\n\nRequired scope: `products.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"gtin\": null,\n \"mpn\": null,\n \"ean\": null,\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition, barely used.\",\n \"category_id\": 4291,\n \"status\": \"active\",\n \"is_reviewed\": true,\n \"price\": {\n \"amount\": 249900,\n \"currency\": \"RON\",\n \"negotiable\": true\n },\n \"stock\": 4,\n \"shipping\": {\n \"ship_with_us\": true,\n \"free_shipping\": false,\n \"shipping_class\": \"bike\",\n \"parcel_tier\": \"large\",\n \"weight_kg\": 14.5,\n \"width_cm\": 80,\n \"height_cm\": 120,\n \"length_cm\": 180\n },\n \"group_id\": null,\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n }\n ],\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226,\n \"value\": null\n }\n ],\n \"created_at\": \"2026-09-01T08:14:22Z\",\n \"updated_at\": \"2026-09-11T16:02:51Z\"\n}" } ] }, { "name": "What a buyer pays, and what it costs you · GET /v1/products/{id}/pricing", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/pricing?country_code=RO&by=", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "pricing" ], "query": [ { "key": "country_code", "value": "RO", "description": "Destination. Defaults to the listing's own country", "disabled": false }, { "key": "by", "value": "", "description": "Set to external_id to look the product up by your identifier", "disabled": true } ] }, "description": "The same figures the product page renders, from the same service — a partner and a buyer are never shown different numbers. Takes a DESTINATION, because delivery and absorption both depend on where the parcel goes; defaults to the listing's own country. Each `status` says who bears that line: `charged` means the buyer, anything else means your company or the platform absorbed it. `delivery.quoted: false` is NOT free delivery — it means we could not price that route at all, and the order may not be placeable there. Its own endpoint rather than a block on the product payload, because it costs a route lookup per product.\n\nRequired scope: `products.read`." }, "response": [ { "name": "What a buyer pays, and what it costs you — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/pricing?country_code=RO&by=", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "pricing" ], "query": [ { "key": "country_code", "value": "RO", "description": "Destination. Defaults to the listing's own country", "disabled": false }, { "key": "by", "value": "", "description": "Set to external_id to look the product up by your identifier", "disabled": true } ] }, "description": "The same figures the product page renders, from the same service — a partner and a buyer are never shown different numbers. Takes a DESTINATION, because delivery and absorption both depend on where the parcel goes; defaults to the listing's own country. Each `status` says who bears that line: `charged` means the buyer, anything else means your company or the platform absorbed it. `delivery.quoted: false` is NOT free delivery — it means we could not price that route at all, and the order may not be placeable there. Its own endpoint rather than a block on the product payload, because it costs a route lookup per product.\n\nRequired scope: `products.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"currency\": \"RON\",\n \"destination_country_code\": \"RO\",\n \"buyer_pays\": {\n \"product\": 120000,\n \"buyer_protection\": {\n \"amount\": 6000,\n \"status\": \"absorbed_by_company\"\n },\n \"delivery\": {\n \"amount\": 2500,\n \"status\": \"charged\",\n \"quoted\": true\n },\n \"total_estimated\": 122500\n },\n \"commission\": {\n \"percentage\": 5,\n \"min_amount\": 499,\n \"max_amount\": null\n },\n \"note\": \"Estimates from the same service the product page renders.\"\n }\n}" } ] }, { "name": "Update price only · PATCH /v1/products/{id}/price", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/price", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "price" ], "query": [] }, "description": "The cheap path for the field ERPs push most often — one UPDATE, no attribute or shipping rewrite. Amount in minor units.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"price\": 179900\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Update price only — 200", "originalRequest": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/price", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "price" ], "query": [] }, "description": "The cheap path for the field ERPs push most often — one UPDATE, no attribute or shipping rewrite. Amount in minor units.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"price\": 179900\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"gtin\": null,\n \"mpn\": null,\n \"ean\": null,\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition, barely used.\",\n \"category_id\": 4291,\n \"status\": \"active\",\n \"is_reviewed\": true,\n \"price\": {\n \"amount\": 249900,\n \"currency\": \"RON\",\n \"negotiable\": true\n },\n \"stock\": 4,\n \"shipping\": {\n \"ship_with_us\": true,\n \"free_shipping\": false,\n \"shipping_class\": \"bike\",\n \"parcel_tier\": \"large\",\n \"weight_kg\": 14.5,\n \"width_cm\": 80,\n \"height_cm\": 120,\n \"length_cm\": 180\n },\n \"group_id\": null,\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n }\n ],\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226,\n \"value\": null\n }\n ],\n \"created_at\": \"2026-09-01T08:14:22Z\",\n \"updated_at\": \"2026-09-11T16:02:51Z\"\n}" } ] }, { "name": "Update stock only · PATCH /v1/products/{id}/stock", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/stock", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "stock" ], "query": [] }, "description": "The cheap path for stock. One UPDATE, nothing else touched.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"stock\": 2\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Update stock only — 200", "originalRequest": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/stock", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "stock" ], "query": [] }, "description": "The cheap path for stock. One UPDATE, nothing else touched.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"stock\": 2\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"gtin\": null,\n \"mpn\": null,\n \"ean\": null,\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition, barely used.\",\n \"category_id\": 4291,\n \"status\": \"active\",\n \"is_reviewed\": true,\n \"price\": {\n \"amount\": 249900,\n \"currency\": \"RON\",\n \"negotiable\": true\n },\n \"stock\": 4,\n \"shipping\": {\n \"ship_with_us\": true,\n \"free_shipping\": false,\n \"shipping_class\": \"bike\",\n \"parcel_tier\": \"large\",\n \"weight_kg\": 14.5,\n \"width_cm\": 80,\n \"height_cm\": 120,\n \"length_cm\": 180\n },\n \"group_id\": null,\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n }\n ],\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226,\n \"value\": null\n }\n ],\n \"created_at\": \"2026-09-01T08:14:22Z\",\n \"updated_at\": \"2026-09-11T16:02:51Z\"\n}" } ] }, { "name": "Create or re-link a variant group · POST /v1/product-groups", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/product-groups", "host": [ "{{base_url}}" ], "path": [ "v1", "product-groups" ], "query": [] }, "description": "One product sold in several sizes or colours. Each variant is its own product with its own price and stock; the group links them so the storefront shows one card with a picker. Pushing the same group again re-links it (200) instead of creating a second one (201).\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"external_group_id\": \"ERP-1001-GROUP\",\n \"products\": [\n {\n \"external_id\": \"ERP-1001\",\n \"size\": \"S\",\n \"color\": \"Negru\"\n },\n {\n \"external_id\": \"ERP-1001-M\",\n \"size\": \"M\",\n \"color\": \"Negru\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Create or re-link a variant group — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/product-groups", "host": [ "{{base_url}}" ], "path": [ "v1", "product-groups" ], "query": [] }, "description": "One product sold in several sizes or colours. Each variant is its own product with its own price and stock; the group links them so the storefront shows one card with a picker. Pushing the same group again re-links it (200) instead of creating a second one (201).\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"external_group_id\": \"ERP-1001-GROUP\",\n \"products\": [\n {\n \"external_id\": \"ERP-1001\",\n \"size\": \"S\",\n \"color\": \"Negru\"\n },\n {\n \"external_id\": \"ERP-1001-M\",\n \"size\": \"M\",\n \"color\": \"Negru\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"external_group_id\": \"ERP-1001-GROUP\",\n \"group_id\": 904,\n \"count\": 2,\n \"variants\": [\n {\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001-S\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"price\": {\n \"amount\": 249900\n },\n \"stock\": 4,\n \"size\": \"S\",\n \"color\": \"Negru\",\n \"gender\": null,\n \"is_representative\": true\n },\n {\n \"product_id\": 237225,\n \"external_id\": \"ERP-1001-M\",\n \"sku\": \"MTB-29-001-M\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"price\": {\n \"amount\": 249900\n },\n \"stock\": 2,\n \"size\": \"M\",\n \"color\": \"Negru\",\n \"gender\": null,\n \"is_representative\": false\n }\n ]\n}" } ] }, { "name": "Create or update a product · POST /v1/products", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products", "host": [ "{{base_url}}" ], "path": [ "v1", "products" ], "query": [] }, "description": "Upsert keyed on your `external_id`: the same call twice updates rather than duplicating, which makes a retried push safe. Required category attributes are enforced exactly as they are for a seller using the dashboard. Send `images` in the same call — one request per product, images included.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"external_id\": \"ERP-1001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition, barely used.\",\n \"category_id\": 4291,\n \"price\": {\n \"amount\": 249900,\n \"currency\": \"RON\",\n \"negotiable\": true\n },\n \"stock\": 4,\n \"sku\": \"MTB-29-001\",\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226\n },\n {\n \"field_id\": 47,\n \"option_id\": 422\n }\n ],\n \"shipping\": {\n \"weight_kg\": 14.5,\n \"width_cm\": 80,\n \"height_cm\": 120,\n \"length_cm\": 180\n },\n \"images\": [\n \"https://cdn.example.com/erp/mtb-front.jpg\",\n \"https://cdn.example.com/erp/mtb-side.jpg\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Create or update a product — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products", "host": [ "{{base_url}}" ], "path": [ "v1", "products" ], "query": [] }, "description": "Upsert keyed on your `external_id`: the same call twice updates rather than duplicating, which makes a retried push safe. Required category attributes are enforced exactly as they are for a seller using the dashboard. Send `images` in the same call — one request per product, images included.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"external_id\": \"ERP-1001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition, barely used.\",\n \"category_id\": 4291,\n \"price\": {\n \"amount\": 249900,\n \"currency\": \"RON\",\n \"negotiable\": true\n },\n \"stock\": 4,\n \"sku\": \"MTB-29-001\",\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226\n },\n {\n \"field_id\": 47,\n \"option_id\": 422\n }\n ],\n \"shipping\": {\n \"weight_kg\": 14.5,\n \"width_cm\": 80,\n \"height_cm\": 120,\n \"length_cm\": 180\n },\n \"images\": [\n \"https://cdn.example.com/erp/mtb-front.jpg\",\n \"https://cdn.example.com/erp/mtb-side.jpg\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"gtin\": null,\n \"mpn\": null,\n \"ean\": null,\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition, barely used.\",\n \"category_id\": 4291,\n \"status\": \"active\",\n \"is_reviewed\": true,\n \"price\": {\n \"amount\": 249900,\n \"currency\": \"RON\",\n \"negotiable\": true\n },\n \"stock\": 4,\n \"shipping\": {\n \"ship_with_us\": true,\n \"free_shipping\": false,\n \"shipping_class\": \"bike\",\n \"parcel_tier\": \"large\",\n \"weight_kg\": 14.5,\n \"width_cm\": 80,\n \"height_cm\": 120,\n \"length_cm\": 180\n },\n \"group_id\": null,\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n }\n ],\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226,\n \"value\": null\n }\n ],\n \"created_at\": \"2026-09-01T08:14:22Z\",\n \"updated_at\": \"2026-09-11T16:02:51Z\"\n}" } ] }, { "name": "Bulk upsert · POST /v1/products/batch", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/batch", "host": [ "{{base_url}}" ], "path": [ "v1", "products", "batch" ], "query": [] }, "description": "Up to 1000 products, worked through on a queue. Returns immediately with a batch id — NOTHING is written yet. Poll the batch for per-item results. Each product takes every field of `POST /v1/products`, `images` included, so a whole catalogue — pictures and all — is a handful of requests.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"products\": [\n {\n \"external_id\": \"ERP-1001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition.\",\n \"category_id\": 4291,\n \"price\": {\n \"amount\": 249900\n },\n \"stock\": 4,\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226\n },\n {\n \"field_id\": 47,\n \"option_id\": 422\n }\n ]\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Bulk upsert — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/batch", "host": [ "{{base_url}}" ], "path": [ "v1", "products", "batch" ], "query": [] }, "description": "Up to 1000 products, worked through on a queue. Returns immediately with a batch id — NOTHING is written yet. Poll the batch for per-item results. Each product takes every field of `POST /v1/products`, `images` included, so a whole catalogue — pictures and all — is a handful of requests.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"products\": [\n {\n \"external_id\": \"ERP-1001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition.\",\n \"category_id\": 4291,\n \"price\": {\n \"amount\": 249900\n },\n \"stock\": 4,\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226\n },\n {\n \"field_id\": 47,\n \"option_id\": 422\n }\n ]\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"batch_id\": \"batch_v4lfngtgb6sxqkzwagrqv8c2\",\n \"status\": \"queued\",\n \"total\": 1,\n \"message\": \"Accepted. Nothing is written yet — poll GET /v1/products/batch/{id} for per-item results.\"\n}" } ] }, { "name": "Archive a product · POST /v1/products/{id}/archive", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/archive", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "archive" ], "query": [] }, "description": "Takes the listing off the marketplace: out of search, the storefront and every cart. Use it when a product leaves your catalogue — stock `0` alone keeps it visible and unbuyable (a sell-out by Biklo orders is different: that archives it, and restocking relists it). Archived as if you had switched it off in the dashboard, so an order that is cancelled later never puts it back on sale. Idempotent; the listing, its id and its history stay, and `POST /v1/products/{id}/unarchive` brings it back.\n\nRequired scope: `products.write`." }, "response": [ { "name": "Archive a product — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/archive", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "archive" ], "query": [] }, "description": "Takes the listing off the marketplace: out of search, the storefront and every cart. Use it when a product leaves your catalogue — stock `0` alone keeps it visible and unbuyable (a sell-out by Biklo orders is different: that archives it, and restocking relists it). Archived as if you had switched it off in the dashboard, so an order that is cancelled later never puts it back on sale. Idempotent; the listing, its id and its history stay, and `POST /v1/products/{id}/unarchive` brings it back.\n\nRequired scope: `products.write`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"gtin\": null,\n \"mpn\": null,\n \"ean\": null,\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition, barely used.\",\n \"category_id\": 4291,\n \"status\": \"archived\",\n \"is_reviewed\": true,\n \"price\": {\n \"amount\": 249900,\n \"currency\": \"RON\",\n \"negotiable\": true\n },\n \"stock\": 4,\n \"shipping\": {\n \"ship_with_us\": true,\n \"free_shipping\": false,\n \"shipping_class\": \"bike\",\n \"parcel_tier\": \"large\",\n \"weight_kg\": 14.5,\n \"width_cm\": 80,\n \"height_cm\": 120,\n \"length_cm\": 180\n },\n \"group_id\": null,\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n }\n ],\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226,\n \"value\": null\n }\n ],\n \"created_at\": \"2026-09-01T08:14:22Z\",\n \"updated_at\": \"2026-09-11T16:02:51Z\"\n}" } ] }, { "name": "Add images · POST /v1/products/{id}/images", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/images", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "images" ], "query": [] }, "description": "Two ways, mixable in one call: `images` as URLs (referenced, nothing downloaded — the way supplier feeds work) and/or `files` as multipart uploads onto our storage. Position 0 is the primary image. For URLs, sending `images` with the product itself (`POST /v1/products`, `PUT`, or the batch) saves this request entirely — this endpoint is for uploads and for adding to what a listing has.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"images\": [\n {\n \"url\": \"https://cdn.example.com/erp/mtb-front.jpg\"\n },\n {\n \"url\": \"https://cdn.example.com/erp/mtb-side.jpg\"\n }\n ],\n \"replace\": false\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Add images — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/images", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "images" ], "query": [] }, "description": "Two ways, mixable in one call: `images` as URLs (referenced, nothing downloaded — the way supplier feeds work) and/or `files` as multipart uploads onto our storage. Position 0 is the primary image. For URLs, sending `images` with the product itself (`POST /v1/products`, `PUT`, or the batch) saves this request entirely — this endpoint is for uploads and for adding to what a listing has.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"images\": [\n {\n \"url\": \"https://cdn.example.com/erp/mtb-front.jpg\"\n },\n {\n \"url\": \"https://cdn.example.com/erp/mtb-side.jpg\"\n }\n ],\n \"replace\": false\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"attached_from_urls\": 2,\n \"uploaded\": 0,\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n },\n {\n \"id\": 108876840,\n \"position\": 1,\n \"path\": null,\n \"source_url\": \"https://cdn.example.com/erp/mtb-side.jpg\"\n }\n ]\n}" } ] }, { "name": "Put a product back on sale · POST /v1/products/{id}/unarchive", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/unarchive", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "unarchive" ], "query": [] }, "description": "The opposite of archive, with a fresh 90-day lease so the expiry job does not archive it again straight away. Idempotent on a listing that is already active. A listing a Biklo order sold out comes back on its own when you send stock above 0, so this is mainly for listings you archived. Refused with `product_reserved` (409) only for a listing with no stock left while an order for it is still in progress — if that order is cancelled or rejected, the product comes back by itself.\n\nRequired scope: `products.write`." }, "response": [ { "name": "Put a product back on sale — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/unarchive", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "unarchive" ], "query": [] }, "description": "The opposite of archive, with a fresh 90-day lease so the expiry job does not archive it again straight away. Idempotent on a listing that is already active. A listing a Biklo order sold out comes back on its own when you send stock above 0, so this is mainly for listings you archived. Refused with `product_reserved` (409) only for a listing with no stock left while an order for it is still in progress — if that order is cancelled or rejected, the product comes back by itself.\n\nRequired scope: `products.write`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"gtin\": null,\n \"mpn\": null,\n \"ean\": null,\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition, barely used.\",\n \"category_id\": 4291,\n \"status\": \"active\",\n \"is_reviewed\": true,\n \"price\": {\n \"amount\": 249900,\n \"currency\": \"RON\",\n \"negotiable\": true\n },\n \"stock\": 4,\n \"shipping\": {\n \"ship_with_us\": true,\n \"free_shipping\": false,\n \"shipping_class\": \"bike\",\n \"parcel_tier\": \"large\",\n \"weight_kg\": 14.5,\n \"width_cm\": 80,\n \"height_cm\": 120,\n \"length_cm\": 180\n },\n \"group_id\": null,\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n }\n ],\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226,\n \"value\": null\n }\n ],\n \"created_at\": \"2026-09-01T08:14:22Z\",\n \"updated_at\": \"2026-09-11T16:02:51Z\"\n}" } ] }, { "name": "Update a product · PUT /v1/products/{id}", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id" ], "query": [] }, "description": "Partial: keys you omit are left alone. Send `attributes` only when you want to replace the whole set.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"title\": \"Bicicleta MTB Hardtail 29 actualizata\",\n \"price\": {\n \"amount\": 199900\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Update a product — 200", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id" ], "query": [] }, "description": "Partial: keys you omit are left alone. Send `attributes` only when you want to replace the whole set.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"title\": \"Bicicleta MTB Hardtail 29 actualizata\",\n \"price\": {\n \"amount\": 199900\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"gtin\": null,\n \"mpn\": null,\n \"ean\": null,\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"description\": \"A hardtail mountain bike in very good condition, barely used.\",\n \"category_id\": 4291,\n \"status\": \"active\",\n \"is_reviewed\": true,\n \"price\": {\n \"amount\": 249900,\n \"currency\": \"RON\",\n \"negotiable\": true\n },\n \"stock\": 4,\n \"shipping\": {\n \"ship_with_us\": true,\n \"free_shipping\": false,\n \"shipping_class\": \"bike\",\n \"parcel_tier\": \"large\",\n \"weight_kg\": 14.5,\n \"width_cm\": 80,\n \"height_cm\": 120,\n \"length_cm\": 180\n },\n \"group_id\": null,\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n }\n ],\n \"attributes\": [\n {\n \"field_id\": 32,\n \"option_id\": 226,\n \"value\": null\n }\n ],\n \"created_at\": \"2026-09-01T08:14:22Z\",\n \"updated_at\": \"2026-09-11T16:02:51Z\"\n}" } ] }, { "name": "Reorder images · PUT /v1/products/{id}/images/order", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/images/order", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "images", "order" ], "query": [] }, "description": "Ids you do not name keep their relative order after the ones you do. The first is the primary image.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"image_ids\": [\n 108876841,\n 108876840,\n 108876839\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Reorder images — 200", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/:id/images/order", "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "images", "order" ], "query": [] }, "description": "Ids you do not name keep their relative order after the ones you do. The first is the primary image.\n\nRequired scope: `products.write`.", "body": { "mode": "raw", "raw": "{\n \"image_ids\": [\n 108876841,\n 108876840,\n 108876839\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"images\": [\n {\n \"id\": 108876841,\n \"position\": 0,\n \"path\": \"files/237224/mtb-front.jpg\",\n \"source_url\": null\n },\n {\n \"id\": 108876840,\n \"position\": 1,\n \"path\": null,\n \"source_url\": \"https://cdn.example.com/erp/mtb-side.jpg\"\n }\n ]\n}" } ] } ] }, { "name": "Questions", "item": [ { "name": "List questions on your listings · GET /v1/questions", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/questions?limit=50&cursor=&unanswered_only=true&product_id=237233&updated_since=2026-09-01T00:00:00Z", "host": [ "{{base_url}}" ], "path": [ "v1", "questions" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "unanswered_only", "value": "true", "description": "Only questions still waiting", "disabled": false }, { "key": "product_id", "value": "237233", "description": "Only questions on one listing", "disabled": false }, { "key": "updated_since", "value": "2026-09-01T00:00:00Z", "description": "Incremental sync", "disabled": false } ] }, "description": "Public questions — these render on the product page for every future buyer, so an unanswered one is visible to everyone. `unanswered_count` is carried on every response so you can badge it without a second call.\n\nRequired scope: `questions.read`." }, "response": [ { "name": "List questions on your listings — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/questions?limit=50&cursor=&unanswered_only=true&product_id=237233&updated_since=2026-09-01T00:00:00Z", "host": [ "{{base_url}}" ], "path": [ "v1", "questions" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "unanswered_only", "value": "true", "description": "Only questions still waiting", "disabled": false }, { "key": "product_id", "value": "237233", "description": "Only questions on one listing", "disabled": false }, { "key": "updated_since", "value": "2026-09-01T00:00:00Z", "description": "Incremental sync", "disabled": false } ] }, "description": "Public questions — these render on the product page for every future buyer, so an unanswered one is visible to everyone. `unanswered_count` is carried on every response so you can badge it without a second call.\n\nRequired scope: `questions.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 2,\n \"next_cursor\": null,\n \"unanswered_count\": 1,\n \"data\": [\n {\n \"id\": 31,\n \"text\": \"What frame size is this?\",\n \"product\": {\n \"id\": 237233,\n \"title\": \"Trek Marlin 7\",\n \"slug\": \"trek-marlin-7\"\n },\n \"asked_by\": {\n \"id\": 9000002,\n \"name\": \"Jane Doe\"\n },\n \"is_answered\": false,\n \"answered_at\": null,\n \"votes\": {\n \"helpful\": 0,\n \"not_helpful\": 0,\n \"same_question\": 0\n },\n \"answers\": [],\n \"created_at\": \"2026-09-10T06:21:50Z\",\n \"updated_at\": \"2026-09-10T06:21:50Z\"\n },\n {\n \"id\": 30,\n \"text\": \"Does it come with pedals?\",\n \"product\": {\n \"id\": 237233,\n \"title\": \"Trek Marlin 7\",\n \"slug\": \"trek-marlin-7\"\n },\n \"asked_by\": {\n \"id\": 9000003,\n \"name\": \"Maria I.\"\n },\n \"is_answered\": true,\n \"answered_at\": \"2026-09-09T11:04:12Z\",\n \"votes\": {\n \"helpful\": 2,\n \"not_helpful\": 0,\n \"same_question\": 1\n },\n \"answers\": [\n {\n \"id\": 14,\n \"text\": \"Yes, flat pedals are included.\",\n \"is_from_seller\": true,\n \"author_name\": \"Bike Shop SRL\",\n \"created_at\": \"2026-09-09T11:04:12Z\",\n \"updated_at\": \"2026-09-09T11:04:12Z\"\n }\n ],\n \"created_at\": \"2026-09-09T10:58:03Z\",\n \"updated_at\": \"2026-09-09T11:04:12Z\"\n }\n ]\n}" } ] }, { "name": "Get one question · GET /v1/questions/{id}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/questions/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "questions", ":id" ], "query": [] }, "description": "With every published answer on it.\n\nRequired scope: `questions.read`." }, "response": [ { "name": "Get one question — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/questions/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "questions", ":id" ], "query": [] }, "description": "With every published answer on it.\n\nRequired scope: `questions.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": 31,\n \"text\": \"What frame size is this?\",\n \"product\": {\n \"id\": 237233,\n \"title\": \"Trek Marlin 7\",\n \"slug\": \"trek-marlin-7\"\n },\n \"asked_by\": {\n \"id\": 9000002,\n \"name\": \"Jane Doe\"\n },\n \"is_answered\": true,\n \"answered_at\": \"2026-09-10T06:21:57Z\",\n \"votes\": {\n \"helpful\": 2,\n \"not_helpful\": 0,\n \"same_question\": 1\n },\n \"answers\": [\n {\n \"id\": 15,\n \"text\": \"Size L — suits 180-190 cm.\",\n \"is_from_seller\": true,\n \"author_name\": \"Bike Shop SRL\",\n \"created_at\": \"2026-09-10T06:21:57Z\",\n \"updated_at\": \"2026-09-10T06:21:57Z\"\n }\n ],\n \"created_at\": \"2026-09-10T06:21:50Z\",\n \"updated_at\": \"2026-09-10T06:21:57Z\"\n }\n}" } ] }, { "name": "Answer a question · POST /v1/questions/{id}/answer", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/questions/:id/answer", "host": [ "{{base_url}}" ], "path": [ "v1", "questions", ":id", "answer" ], "query": [] }, "description": "Answers are moderated exactly as they are on the site. Check `is_published`: when it is false the answer is held for review and is NOT yet on the listing, so tell your user that rather than showing it as live.\n\nRequired scope: `questions.write`.", "body": { "mode": "raw", "raw": "{\n \"text\": \"Size L — suits 180-190 cm.\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Answer a question — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/questions/:id/answer", "host": [ "{{base_url}}" ], "path": [ "v1", "questions", ":id", "answer" ], "query": [] }, "description": "Answers are moderated exactly as they are on the site. Check `is_published`: when it is false the answer is held for review and is NOT yet on the listing, so tell your user that rather than showing it as live.\n\nRequired scope: `questions.write`.", "body": { "mode": "raw", "raw": "{\n \"text\": \"Size L — suits 180-190 cm.\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": 15,\n \"question_id\": 31,\n \"text\": \"Size L — suits 180-190 cm.\",\n \"status\": \"published\",\n \"is_published\": true,\n \"created_at\": \"2026-09-10T06:21:57Z\"\n }\n}" } ] } ] }, { "name": "Sandbox test data", "item": [ { "name": "Sandbox: have a buyer write to you · POST /v1/sandbox/messages", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/sandbox/messages", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "messages" ], "query": [] }, "description": "Sandbox only. Buyers are the ones who START conversations and the sandbox has none, so without this your inbox is permanently empty. A synthetic buyer opens (or continues) a conversation about one of your own listings, through the same write path a real buyer uses.\n\nRequired scope: `messages.write`.\n\n**Sandbox only** — this route does not exist in production.", "body": { "mode": "raw", "raw": "{\n \"product_id\": 237233,\n \"body\": \"Is this still available?\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Sandbox: have a buyer write to you — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/sandbox/messages", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "messages" ], "query": [] }, "description": "Sandbox only. Buyers are the ones who START conversations and the sandbox has none, so without this your inbox is permanently empty. A synthetic buyer opens (or continues) a conversation about one of your own listings, through the same write path a real buyer uses.\n\nRequired scope: `messages.write`.\n\n**Sandbox only** — this route does not exist in production.", "body": { "mode": "raw", "raw": "{\n \"product_id\": 237233,\n \"body\": \"Is this still available?\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"thread_id\": 107373,\n \"message_id\": 174420,\n \"product_id\": 237233,\n \"from\": \"buyer\",\n \"body\": \"Is this still available?\"\n }\n}" } ] }, { "name": "Create a test order (sandbox only) · POST /v1/sandbox/orders", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/sandbox/orders", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "orders" ], "query": [] }, "description": "404 in production. The sandbox has no buyers, so this fabricates an order from a synthetic buyer against one of your own products. No payment exists and no courier is contacted. It sends `order.created` to your webhooks like a real order does — even though you asked for it, because it stands in for a buyer.\n\nRequired scope: `orders.write`.\n\n**Sandbox only** — this route does not exist in production.", "body": { "mode": "raw", "raw": "{\n \"external_id\": \"ERP-1001\",\n \"quantity\": 2\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Create a test order (sandbox only) — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/sandbox/orders", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "orders" ], "query": [] }, "description": "404 in production. The sandbox has no buyers, so this fabricates an order from a synthetic buyer against one of your own products. No payment exists and no courier is contacted. It sends `order.created` to your webhooks like a real order does — even though you asked for it, because it stands in for a buyer.\n\nRequired scope: `orders.write`.\n\n**Sandbox only** — this route does not exist in production.", "body": { "mode": "raw", "raw": "{\n \"external_id\": \"ERP-1001\",\n \"quantity\": 2\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"order\": {\n \"id\": 711,\n \"reference\": \"SBXORD-SJP6NHXY\",\n \"status\": \"pending\",\n \"can_accept\": false,\n \"has_awb\": true,\n \"total\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n },\n \"refunded\": {\n \"amount\": 0,\n \"currency\": \"RON\"\n },\n \"items\": [\n {\n \"id\": 1123,\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"quantity\": 2,\n \"quantity_ordered\": 2,\n \"quantity_short\": 0,\n \"unit_price\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"total_price\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n }\n }\n ],\n \"awb\": {\n \"number\": \"SBX0000000711\",\n \"tracking_url\": \"https://sandbox-api.biklo.com/track/SBX0000000711\"\n },\n \"is_dropshipping\": false,\n \"created_at\": \"2026-09-11T09:20:14Z\",\n \"updated_at\": \"2026-09-11T10:02:47Z\",\n \"accepted_at\": \"2026-09-11T10:02:47Z\",\n \"delivered_at\": null,\n \"expires_at\": \"2026-09-13T09:20:14Z\",\n \"notes_from_buyer\": \"Please call before delivery.\",\n \"courier_id\": 1,\n \"seller_invoice\": null,\n \"fees\": {\n \"platform_fee\": 17990,\n \"shipping\": 2500,\n \"currency\": \"RON\"\n },\n \"delivery\": {\n \"recipient\": \"John Doe\",\n \"phone\": \"07xxxxxxxx\",\n \"city\": \"Craiova\",\n \"county\": \"Dolj\",\n \"postcode\": \"200000\",\n \"country\": \"RO\",\n \"is_locker\": false\n },\n \"refunds\": [],\n \"parcels\": [\n {\n \"id\": 4012,\n \"sequence_no\": 1,\n \"weight_kg\": 2.4,\n \"length_cm\": 40,\n \"width_cm\": 30,\n \"height_cm\": 20,\n \"is_seller_declared\": true,\n \"items\": [\n {\n \"order_item_id\": 1123,\n \"quantity\": 2\n }\n ]\n }\n ]\n },\n \"note\": \"A test order from a synthetic buyer. No payment exists and no courier was contacted.\"\n}" } ] }, { "name": "Advance a test order (sandbox only) · POST /v1/sandbox/orders/{id}/advance", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/sandbox/orders/:id/advance", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "orders", ":id", "advance" ], "query": [] }, "description": "404 in production. Plays the buyer and the courier: walks the order to the next step, or straight to the one you name, in seconds instead of days. It behaves like production — the order's own `status` only goes `pending → accepted`; after that the courier steps add courier events to the AWB (booking the sandbox courier first if nobody has) and the order stays `accepted`. Follow the parcel on `GET /v1/orders/{id}/tracking`; `delivered` also stamps `delivered_at` and starts the return window, as a real courier's delivery does.\n\nRequired scope: `orders.write`.\n\n**Sandbox only** — this route does not exist in production.", "body": { "mode": "raw", "raw": "{\n \"status\": \"delivered\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Advance a test order (sandbox only) — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/sandbox/orders/:id/advance", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "orders", ":id", "advance" ], "query": [] }, "description": "404 in production. Plays the buyer and the courier: walks the order to the next step, or straight to the one you name, in seconds instead of days. It behaves like production — the order's own `status` only goes `pending → accepted`; after that the courier steps add courier events to the AWB (booking the sandbox courier first if nobody has) and the order stays `accepted`. Follow the parcel on `GET /v1/orders/{id}/tracking`; `delivered` also stamps `delivered_at` and starts the return window, as a real courier's delivery does.\n\nRequired scope: `orders.write`.\n\n**Sandbox only** — this route does not exist in production.", "body": { "mode": "raw", "raw": "{\n \"status\": \"delivered\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"from\": \"in_delivery\",\n \"to\": \"delivered\",\n \"order\": {\n \"id\": 711,\n \"reference\": \"SBXORD-SJP6NHXY\",\n \"status\": \"accepted\",\n \"can_accept\": false,\n \"has_awb\": true,\n \"total\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n },\n \"refunded\": {\n \"amount\": 0,\n \"currency\": \"RON\"\n },\n \"items\": [\n {\n \"id\": 1123,\n \"product_id\": 237224,\n \"external_id\": \"ERP-1001\",\n \"sku\": \"MTB-29-001\",\n \"title\": \"Bicicleta MTB Hardtail 29 inch\",\n \"quantity\": 2,\n \"quantity_ordered\": 2,\n \"quantity_short\": 0,\n \"unit_price\": {\n \"amount\": 179900,\n \"currency\": \"RON\"\n },\n \"total_price\": {\n \"amount\": 359800,\n \"currency\": \"RON\"\n }\n }\n ],\n \"awb\": {\n \"number\": \"SBX0000000711\",\n \"tracking_url\": \"https://sandbox-api.biklo.com/track/SBX0000000711\"\n },\n \"is_dropshipping\": false,\n \"created_at\": \"2026-09-11T09:20:14Z\",\n \"updated_at\": \"2026-09-11T10:02:47Z\",\n \"accepted_at\": \"2026-09-11T10:02:47Z\",\n \"delivered_at\": null,\n \"expires_at\": \"2026-09-13T09:20:14Z\",\n \"notes_from_buyer\": \"Please call before delivery.\",\n \"courier_id\": 1,\n \"seller_invoice\": null,\n \"fees\": {\n \"platform_fee\": 17990,\n \"shipping\": 2500,\n \"currency\": \"RON\"\n },\n \"delivery\": {\n \"recipient\": \"John Doe\",\n \"phone\": \"07xxxxxxxx\",\n \"city\": \"Craiova\",\n \"county\": \"Dolj\",\n \"postcode\": \"200000\",\n \"country\": \"RO\",\n \"is_locker\": false\n },\n \"refunds\": [],\n \"parcels\": [\n {\n \"id\": 4012,\n \"sequence_no\": 1,\n \"weight_kg\": 2.4,\n \"length_cm\": 40,\n \"width_cm\": 30,\n \"height_cm\": 20,\n \"is_seller_declared\": true,\n \"items\": [\n {\n \"order_item_id\": 1123,\n \"quantity\": 2\n }\n ]\n }\n ]\n }\n}" } ] }, { "name": "Sandbox: have a buyer ask a question · POST /v1/sandbox/questions", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/sandbox/questions", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "questions" ], "query": [] }, "description": "Sandbox only. `published_by_sandbox` is true when auto-publish is off and we published the question anyway so you have something readable to integrate against.\n\nRequired scope: `questions.write`.\n\n**Sandbox only** — this route does not exist in production.", "body": { "mode": "raw", "raw": "{\n \"product_id\": 237233,\n \"text\": \"What frame size is this?\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Sandbox: have a buyer ask a question — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/sandbox/questions", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "questions" ], "query": [] }, "description": "Sandbox only. `published_by_sandbox` is true when auto-publish is off and we published the question anyway so you have something readable to integrate against.\n\nRequired scope: `questions.write`.\n\n**Sandbox only** — this route does not exist in production.", "body": { "mode": "raw", "raw": "{\n \"product_id\": 237233,\n \"text\": \"What frame size is this?\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"question_id\": 31,\n \"product_id\": 237233,\n \"text\": \"What frame size is this?\",\n \"status\": \"published\",\n \"published_by_sandbox\": false\n }\n}" } ] }, { "name": "Sandbox: skip the settlement wait · POST /v1/sandbox/withdrawals/advance", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/sandbox/withdrawals/advance", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "withdrawals", "advance" ], "query": [] }, "description": "Sandbox only. Stripe test-mode payouts are REAL payouts and sit `pending` until Stripe settles them, which takes days. This skips the waiting and nothing else — Stripe is never simulated, only its clock is short-circuited.\n\nRequired scope: `wallet.withdraw`.\n\n**Sandbox only** — this route does not exist in production." }, "response": [ { "name": "Sandbox: skip the settlement wait — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/sandbox/withdrawals/advance", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "withdrawals", "advance" ], "query": [] }, "description": "Sandbox only. Stripe test-mode payouts are REAL payouts and sit `pending` until Stripe settles them, which takes days. This skips the waiting and nothing else — Stripe is never simulated, only its clock is short-circuited.\n\nRequired scope: `wallet.withdraw`.\n\n**Sandbox only** — this route does not exist in production." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"payouts_created\": 1,\n \"lots_marked_paid_out\": 3,\n \"errors\": []\n }\n}" } ] } ] }, { "name": "Threads", "item": [ { "name": "List buyer conversations · GET /v1/threads", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/threads?limit=50&cursor=&unread_only=true&product_id=237233&updated_since=2026-09-01T00:00:00Z", "host": [ "{{base_url}}" ], "path": [ "v1", "threads" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor from the previous page", "disabled": true }, { "key": "unread_only", "value": "true", "description": "Only conversations you have not read", "disabled": false }, { "key": "product_id", "value": "237233", "description": "Only conversations about one listing", "disabled": false }, { "key": "updated_since", "value": "2026-09-01T00:00:00Z", "description": "Incremental sync", "disabled": false } ] }, "description": "Conversations on your listings, newest activity first. Buyers are a display name and an id — never an email or a phone number. Use `unread_only=true` for the ones actually waiting on you.\n\nRequired scope: `messages.read`." }, "response": [ { "name": "List buyer conversations — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/threads?limit=50&cursor=&unread_only=true&product_id=237233&updated_since=2026-09-01T00:00:00Z", "host": [ "{{base_url}}" ], "path": [ "v1", "threads" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor from the previous page", "disabled": true }, { "key": "unread_only", "value": "true", "description": "Only conversations you have not read", "disabled": false }, { "key": "product_id", "value": "237233", "description": "Only conversations about one listing", "disabled": false }, { "key": "updated_since", "value": "2026-09-01T00:00:00Z", "description": "Incremental sync", "disabled": false } ] }, "description": "Conversations on your listings, newest activity first. Buyers are a display name and an id — never an email or a phone number. Use `unread_only=true` for the ones actually waiting on you.\n\nRequired scope: `messages.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": 107373,\n \"subject\": \"Trek Marlin 7\",\n \"product\": {\n \"id\": 237233,\n \"title\": \"Trek Marlin 7\",\n \"slug\": \"trek-marlin-7\"\n },\n \"buyer\": {\n \"id\": 9000002,\n \"name\": \"Jane Doe\"\n },\n \"last_message\": {\n \"id\": 174420,\n \"from\": \"buyer\",\n \"preview\": \"Is this still available?\",\n \"created_at\": \"2026-09-10T06:15:18Z\"\n },\n \"is_unread\": true,\n \"created_at\": \"2026-09-10T06:15:18Z\",\n \"updated_at\": \"2026-09-10T06:15:18Z\"\n }\n ]\n}" } ] }, { "name": "Get one conversation · GET /v1/threads/{id}", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/threads/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "threads", ":id" ], "query": [] }, "description": "The same shape as a row in the list. 404 if the conversation is not on one of your listings.\n\nRequired scope: `messages.read`." }, "response": [ { "name": "Get one conversation — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/threads/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "threads", ":id" ], "query": [] }, "description": "The same shape as a row in the list. 404 if the conversation is not on one of your listings.\n\nRequired scope: `messages.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": 107373,\n \"subject\": \"Trek Marlin 7\",\n \"product\": {\n \"id\": 237233,\n \"title\": \"Trek Marlin 7\",\n \"slug\": \"trek-marlin-7\"\n },\n \"buyer\": {\n \"id\": 9000002,\n \"name\": \"Jane Doe\"\n },\n \"last_message\": {\n \"id\": 174420,\n \"from\": \"buyer\",\n \"preview\": \"Is this still available?\",\n \"created_at\": \"2026-09-10T06:15:18Z\"\n },\n \"is_unread\": true,\n \"created_at\": \"2026-09-10T06:15:18Z\",\n \"updated_at\": \"2026-09-10T06:15:18Z\"\n }\n}" } ] }, { "name": "List messages in a conversation · GET /v1/threads/{id}/messages", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/threads/:id/messages?limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "threads", ":id", "messages" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true } ] }, "description": "Newest first. `body` is the text as STORED — when chat protection masked contact details, this is the masked version, which is what the buyer sees too.\n\nRequired scope: `messages.read`." }, "response": [ { "name": "List messages in a conversation — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/threads/:id/messages?limit=50&cursor=", "host": [ "{{base_url}}" ], "path": [ "v1", "threads", ":id", "messages" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true } ] }, "description": "Newest first. `body` is the text as STORED — when chat protection masked contact details, this is the masked version, which is what the buyer sees too.\n\nRequired scope: `messages.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": 174420,\n \"from\": \"buyer\",\n \"author\": {\n \"id\": 9000002,\n \"name\": \"Jane Doe\"\n },\n \"body\": \"Is this still available?\",\n \"has_attachment\": false,\n \"type\": \"text\",\n \"created_at\": \"2026-09-10T06:15:18Z\"\n }\n ]\n}" } ] }, { "name": "Reply to a buyer · POST /v1/threads/{id}/messages", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/threads/:id/messages", "host": [ "{{base_url}}" ], "path": [ "v1", "threads", ":id", "messages" ], "query": [] }, "description": "Every reply passes through the same chat-protection scan the seller dashboard applies. A message carrying contact details is refused with 422 `blocked_by_chat_protection` and a `detected` list saying what was found, or is masked before it is stored — check `chat_protection.was_masked` and show your user the `body` we return, not the one you sent.\n\nRequired scope: `messages.write`.", "body": { "mode": "raw", "raw": "{\n \"body\": \"Yes, it is in stock — we ship within 24 hours.\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Reply to a buyer — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/threads/:id/messages", "host": [ "{{base_url}}" ], "path": [ "v1", "threads", ":id", "messages" ], "query": [] }, "description": "Every reply passes through the same chat-protection scan the seller dashboard applies. A message carrying contact details is refused with 422 `blocked_by_chat_protection` and a `detected` list saying what was found, or is masked before it is stored — check `chat_protection.was_masked` and show your user the `body` we return, not the one you sent.\n\nRequired scope: `messages.write`.", "body": { "mode": "raw", "raw": "{\n \"body\": \"Yes, it is in stock — we ship within 24 hours.\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": 174421,\n \"thread_id\": 107373,\n \"from\": \"seller\",\n \"body\": \"Yes, it is in stock — we ship within 24 hours.\",\n \"created_at\": \"2026-09-10T06:15:30Z\"\n },\n \"chat_protection\": {\n \"decision\": \"allow\",\n \"was_masked\": false\n }\n}" } ] }, { "name": "Mark a conversation read · POST /v1/threads/{id}/read", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/threads/:id/read", "host": [ "{{base_url}}" ], "path": [ "v1", "threads", ":id", "read" ], "query": [] }, "description": "Call this once your own inbox has shown the messages. Without it the seller dashboard keeps reporting conversations as unread that your users have already dealt with.\n\nRequired scope: `messages.write`." }, "response": [ { "name": "Mark a conversation read — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/threads/:id/read", "host": [ "{{base_url}}" ], "path": [ "v1", "threads", ":id", "read" ], "query": [] }, "description": "Call this once your own inbox has shown the messages. Without it the seller dashboard keeps reporting conversations as unread that your users have already dealt with.\n\nRequired scope: `messages.write`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": 107373,\n \"is_unread\": false\n }\n}" } ] } ] }, { "name": "Wallet", "item": [ { "name": "Payout onboarding state · GET /v1/wallet/account", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/account", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "account" ], "query": [] }, "description": "Check this BEFORE offering a withdrawal button. Payout onboarding runs on Stripe Connect, which collects identity documents directly in a hosted browser flow — it CANNOT be completed through this API and no endpoint for it will ever exist. `requirements.currently_due` carries Stripe's own field names for what is still missing, and `next_step` says what to tell your user.\n\nRequired scope: `wallet.read`." }, "response": [ { "name": "Payout onboarding state — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/account", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "account" ], "query": [] }, "description": "Check this BEFORE offering a withdrawal button. Payout onboarding runs on Stripe Connect, which collects identity documents directly in a hosted browser flow — it CANNOT be completed through this API and no endpoint for it will ever exist. `requirements.currently_due` carries Stripe's own field names for what is still missing, and `next_step` says what to tell your user.\n\nRequired scope: `wallet.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"has_account\": true,\n \"can_withdraw\": true,\n \"onboarding_status\": \"complete\",\n \"payouts_enabled\": true,\n \"details_submitted\": true,\n \"requirements\": {\n \"currently_due\": [],\n \"past_due\": [],\n \"pending_verification\": [],\n \"disabled_reason\": null\n },\n \"bank_accounts\": [\n {\n \"last4\": \"0000\",\n \"currency\": \"RON\",\n \"country\": \"RO\"\n }\n ],\n \"next_step\": {\n \"action\": \"none\",\n \"message\": \"This account can receive payouts.\"\n }\n }\n}" } ] }, { "name": "Balances per currency · GET /v1/wallet/balance", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/balance", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "balance" ], "query": [] }, "description": "A LIST, not a number: a seller trading cross-border holds several currencies at once. Every figure is minor units. When money is `blocked` and cannot be withdrawn, the response also carries an `onboarding` block saying why. `settled_to_fees` is terminal: the company's absorbed fees consumed the whole order, so nothing was transferred and nothing was refunded.\n\nRequired scope: `wallet.read`." }, "response": [ { "name": "Balances per currency — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/balance", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "balance" ], "query": [] }, "description": "A LIST, not a number: a seller trading cross-border holds several currencies at once. Every figure is minor units. When money is `blocked` and cannot be withdrawn, the response also carries an `onboarding` block saying why. `settled_to_fees` is terminal: the company's absorbed fees consumed the whole order, so nothing was transferred and nothing was refunded.\n\nRequired scope: `wallet.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"currency\": \"RON\",\n \"pending\": 123400,\n \"available\": 45000,\n \"paid_out\": 890000,\n \"refunded\": 0,\n \"blocked\": 0,\n \"debt\": 0,\n \"settled_to_fees\": 0,\n \"under_review\": 0\n }\n ],\n \"can_withdraw\": true\n}" } ] }, { "name": "The append-only ledger · GET /v1/wallet/ledger", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/ledger?limit=50&cursor=¤cy=RON&order_id=716&entry_type=payout_paid", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "ledger" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "currency", "value": "RON", "description": "Filter by currency", "disabled": false }, { "key": "order_id", "value": "716", "description": "Entries for one order", "disabled": false }, { "key": "entry_type", "value": "payout_paid", "description": "Filter by movement type", "disabled": false } ] }, "description": "Every movement, in order. Reconcile against THIS, not against the balance: balances are a current view, the ledger is the history.\n\nRequired scope: `wallet.read`." }, "response": [ { "name": "The append-only ledger — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/ledger?limit=50&cursor=¤cy=RON&order_id=716&entry_type=payout_paid", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "ledger" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "currency", "value": "RON", "description": "Filter by currency", "disabled": false }, { "key": "order_id", "value": "716", "description": "Entries for one order", "disabled": false }, { "key": "entry_type", "value": "payout_paid", "description": "Filter by movement type", "disabled": false } ] }, "description": "Every movement, in order. Reconcile against THIS, not against the balance: balances are a current view, the ledger is the history.\n\nRequired scope: `wallet.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": 224550,\n \"lot_id\": 1091,\n \"order_id\": 716,\n \"direction\": \"credit\",\n \"type\": \"return_window_started\",\n \"amount\": 123400,\n \"currency\": \"RON\",\n \"balance_category\": \"pending\",\n \"created_at\": \"2026-09-10T07:01:08Z\"\n }\n ]\n}" } ] }, { "name": "Money per order · GET /v1/wallet/lots", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/lots?limit=50&cursor=&status=ready_to_transfer¤cy=RON&order_id=716&updated_since=2026-09-01T00:00:00Z", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "lots" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "status", "value": "ready_to_transfer", "description": "Filter by lot status", "disabled": false }, { "key": "currency", "value": "RON", "description": "Filter by currency", "disabled": false }, { "key": "order_id", "value": "716", "description": "The lot for one order", "disabled": false }, { "key": "updated_since", "value": "2026-09-01T00:00:00Z", "description": "Incremental sync", "disabled": false } ] }, "description": "One row per order. `balance_bucket` says which bucket in GET /v1/wallet/balance this lot counts towards, so you can reconcile the two without learning our internal statuses. `net_transferred_amount` is what actually reached the seller — NOT `amount` when the company absorbed fees, because the surcharge is withheld at transfer. Reconcile against the net.\n\nRequired scope: `wallet.read`." }, "response": [ { "name": "Money per order — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/lots?limit=50&cursor=&status=ready_to_transfer¤cy=RON&order_id=716&updated_since=2026-09-01T00:00:00Z", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "lots" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false }, { "key": "cursor", "value": "", "description": "next_cursor", "disabled": true }, { "key": "status", "value": "ready_to_transfer", "description": "Filter by lot status", "disabled": false }, { "key": "currency", "value": "RON", "description": "Filter by currency", "disabled": false }, { "key": "order_id", "value": "716", "description": "The lot for one order", "disabled": false }, { "key": "updated_since", "value": "2026-09-01T00:00:00Z", "description": "Incremental sync", "disabled": false } ] }, "description": "One row per order. `balance_bucket` says which bucket in GET /v1/wallet/balance this lot counts towards, so you can reconcile the two without learning our internal statuses. `net_transferred_amount` is what actually reached the seller — NOT `amount` when the company absorbed fees, because the surcharge is withheld at transfer. Reconcile against the net.\n\nRequired scope: `wallet.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"next_cursor\": null,\n \"data\": [\n {\n \"id\": 1091,\n \"order_id\": 716,\n \"amount\": 123400,\n \"currency\": \"RON\",\n \"status\": \"return_window\",\n \"balance_bucket\": \"pending\",\n \"is_withdrawable\": false,\n \"held_for_return\": false,\n \"net_transferred_amount\": null,\n \"return_window_expires_at\": \"2026-09-24T07:01:08Z\",\n \"withdrawal_id\": null\n }\n ]\n}" } ] }, { "name": "Payout history · GET /v1/wallet/withdrawals", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/withdrawals?limit=50", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "withdrawals" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false } ] }, "description": "Read from Stripe. If Stripe cannot be reached we fall back to our own rows and mark them `source: local` — you will never see an empty list that wrongly implies no money ever moved.\n\nRequired scope: `wallet.read`." }, "response": [ { "name": "Payout history — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/withdrawals?limit=50", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "withdrawals" ], "query": [ { "key": "limit", "value": "50", "description": "Max 100", "disabled": false } ] }, "description": "Read from Stripe. If Stripe cannot be reached we fall back to our own rows and mark them `source: local` — you will never see an empty list that wrongly implies no money ever moved.\n\nRequired scope: `wallet.read`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"po_1QxyzABC\",\n \"amount\": 45000,\n \"currency\": \"RON\",\n \"status\": \"paid\",\n \"orders_count\": 3,\n \"bank_reference\": \"ARN123456789\",\n \"created_at\": \"2026-09-08T09:00:00Z\",\n \"arrival_at\": \"2026-09-10T00:00:00Z\"\n }\n ]\n}" } ] }, { "name": "Withdraw to the bank · POST /v1/wallet/withdrawals", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/withdrawals", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "withdrawals" ], "query": [] }, "description": "Send `amount` and `currency` together or neither — an amount without a currency is ambiguous the moment a seller holds two, so it is refused rather than guessed. With neither, everything available is withdrawn per currency. `status: funds_settling` is NOT a failure: the money was released and is settling at Stripe. A `payout_failed` is almost always a bank account that cannot receive the balance currency. Returns 409 `onboarding_required` when the seller has not finished Stripe onboarding in a browser.\n\nRequired scope: `wallet.withdraw`.", "body": { "mode": "raw", "raw": "{\n \"amount\": 45000,\n \"currency\": \"RON\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Withdraw to the bank — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/wallet/withdrawals", "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "withdrawals" ], "query": [] }, "description": "Send `amount` and `currency` together or neither — an amount without a currency is ambiguous the moment a seller holds two, so it is refused rather than guessed. With neither, everything available is withdrawn per currency. `status: funds_settling` is NOT a failure: the money was released and is settling at Stripe. A `payout_failed` is almost always a bank account that cannot receive the balance currency. Returns 409 `onboarding_required` when the seller has not finished Stripe onboarding in a browser.\n\nRequired scope: `wallet.withdraw`.", "body": { "mode": "raw", "raw": "{\n \"amount\": 45000,\n \"currency\": \"RON\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"status\": \"payout_created\",\n \"withdrawals\": [\n {\n \"id\": \"po_1QxyzABC\",\n \"amount\": 45000,\n \"currency\": \"RON\",\n \"status\": \"pending\"\n }\n ],\n \"transferred_lots\": 3,\n \"settling\": []\n }\n}" } ] } ] }, { "name": "Webhooks", "item": [ { "name": "Delete an endpoint · DELETE /v1/webhooks/{id}", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", ":id" ], "query": [] }, "description": "Stops delivery immediately.\n\nRequired scope: `webhooks.manage`." }, "response": [ { "name": "Delete an endpoint — 200", "originalRequest": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", ":id" ], "query": [] }, "description": "Stops delivery immediately.\n\nRequired scope: `webhooks.manage`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"deleted\": true,\n \"id\": 1\n}" } ] }, { "name": "List your endpoints · GET /v1/webhooks", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks" ], "query": [] }, "description": "Also returns `available_events`, the full list you may subscribe to.\n\nRequired scope: `webhooks.manage`." }, "response": [ { "name": "List your endpoints — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks" ], "query": [] }, "description": "Also returns `available_events`, the full list you may subscribe to.\n\nRequired scope: `webhooks.manage`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"data\": [\n {\n \"id\": 1,\n \"url\": \"https://erp.example.com/hooks\",\n \"events\": [\n \"order.created\"\n ],\n \"is_active\": true,\n \"consecutive_failures\": 0,\n \"disabled_at\": null,\n \"headers\": [\n {\n \"name\": \"X-Api-Key\",\n \"preview\": \"the ••••••••\"\n }\n ],\n \"secret_prefix\": \"whsec_64Ky4…\"\n }\n ],\n \"available_events\": [\n \"order.created\",\n \"order.status_changed\"\n ]\n}" } ] }, { "name": "Delivery log · GET /v1/webhooks/{id}/deliveries", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/:id/deliveries?status=", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", ":id", "deliveries" ], "query": [ { "key": "status", "value": "", "description": "pending | delivered | failed | abandoned", "disabled": true } ] }, "description": "What happened to every event we sent you — the answer to \"we never got the order\".\n\nRequired scope: `webhooks.manage`." }, "response": [ { "name": "Delivery log — 200", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/:id/deliveries?status=", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", ":id", "deliveries" ], "query": [ { "key": "status", "value": "", "description": "pending | delivered | failed | abandoned", "disabled": true } ] }, "description": "What happened to every event we sent you — the answer to \"we never got the order\".\n\nRequired scope: `webhooks.manage`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"count\": 1,\n \"data\": [\n {\n \"id\": 3,\n \"event\": \"order.created\",\n \"event_id\": \"evt_vlvslhcxut3gj4oikfnqyf7n\",\n \"status\": \"delivered\",\n \"attempts\": 1,\n \"response_status\": 200\n }\n ]\n}" } ] }, { "name": "Register an endpoint · POST /v1/webhooks", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks" ], "query": [] }, "description": "The signing secret is returned ONCE. Verify every delivery: X-Biklo-Signature is `t=,v1=hmac_sha256(timestamp + \".\" + raw_body, secret)` — the same scheme Stripe uses. An empty `events` list means every event.\n\nRequired scope: `webhooks.manage`.", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://erp.example.com/hooks/biklo\",\n \"events\": [\n \"order.created\",\n \"order.status_changed\"\n ],\n \"headers\": [\n {\n \"name\": \"X-Api-Key\",\n \"value\": \"the value your gateway expects\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Register an endpoint — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks" ], "query": [] }, "description": "The signing secret is returned ONCE. Verify every delivery: X-Biklo-Signature is `t=,v1=hmac_sha256(timestamp + \".\" + raw_body, secret)` — the same scheme Stripe uses. An empty `events` list means every event.\n\nRequired scope: `webhooks.manage`.", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://erp.example.com/hooks/biklo\",\n \"events\": [\n \"order.created\",\n \"order.status_changed\"\n ],\n \"headers\": [\n {\n \"name\": \"X-Api-Key\",\n \"value\": \"the value your gateway expects\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 1,\n \"url\": \"https://erp.example.com/hooks/biklo\",\n \"events\": [\n \"order.created\",\n \"order.status_changed\"\n ],\n \"is_active\": true,\n \"headers\": [\n {\n \"name\": \"X-Api-Key\",\n \"preview\": \"the ••••••••\"\n }\n ],\n \"secret\": \"whsec_…\",\n \"secret_note\": \"Shown once.\"\n}" } ] }, { "name": "Replay a delivery · POST /v1/webhooks/deliveries/{deliveryId}/replay", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/deliveries/:deliveryId/replay", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", "deliveries", ":deliveryId", "replay" ], "query": [] }, "description": "Re-sends with the SAME event_id, so your handler can deduplicate.\n\nRequired scope: `webhooks.manage`." }, "response": [ { "name": "Replay a delivery — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/deliveries/:deliveryId/replay", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", "deliveries", ":deliveryId", "replay" ], "query": [] }, "description": "Re-sends with the SAME event_id, so your handler can deduplicate.\n\nRequired scope: `webhooks.manage`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 3,\n \"status\": \"pending\",\n \"replayed\": true\n}" } ] }, { "name": "Re-enable an endpoint · POST /v1/webhooks/{id}/enable", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/:id/enable", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", ":id", "enable" ], "query": [] }, "description": "We switch an endpoint off after 20 consecutive failures. Once you have fixed it, this brings it back and clears the counter.\n\nRequired scope: `webhooks.manage`." }, "response": [ { "name": "Re-enable an endpoint — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/:id/enable", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", ":id", "enable" ], "query": [] }, "description": "We switch an endpoint off after 20 consecutive failures. Once you have fixed it, this brings it back and clears the counter.\n\nRequired scope: `webhooks.manage`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 1,\n \"is_active\": true,\n \"consecutive_failures\": 0,\n \"disabled_at\": null\n}" } ] }, { "name": "Send yourself a test webhook · POST /v1/webhooks/{id}/test", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/:id/test", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", ":id", "test" ], "query": [] }, "description": "Queues a `test.ping` to this endpoint so you can wire up a receiver without creating a real order first. It travels the **same path as every real event** — same queue, same headers, same HMAC signature — so a delivery that arrives and verifies here proves the real ones will too. Sent regardless of what the endpoint subscribes to, because an integrator testing a receiver has not necessarily decided which events they want yet. `202` means queued, not delivered: the outcome appears on `GET /v1/webhooks/{id}/deliveries` a moment later. Refused with `409 endpoint_disabled` if the endpoint is switched off.\n\nRequired scope: `webhooks.manage`." }, "response": [ { "name": "Send yourself a test webhook — 200", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/:id/test", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", ":id", "test" ], "query": [] }, "description": "Queues a `test.ping` to this endpoint so you can wire up a receiver without creating a real order first. It travels the **same path as every real event** — same queue, same headers, same HMAC signature — so a delivery that arrives and verifies here proves the real ones will too. Sent regardless of what the endpoint subscribes to, because an integrator testing a receiver has not necessarily decided which events they want yet. `202` means queued, not delivered: the outcome appears on `GET /v1/webhooks/{id}/deliveries` a moment later. Refused with `409 endpoint_disabled` if the endpoint is switched off.\n\nRequired scope: `webhooks.manage`." }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"queued\": true,\n \"delivery_id\": 9412,\n \"event_id\": \"evt_94q9tgtrsqymkrnwjdxbyfeh\",\n \"event\": \"test.ping\",\n \"url\": \"https://erp.example.com/hooks/biklo\",\n \"deliveries_url\": \"/v1/webhooks/1/deliveries\"\n}" } ] }, { "name": "Edit an endpoint · PUT /v1/webhooks/{id}", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", ":id" ], "query": [] }, "description": "Change what an endpoint subscribes to, or replace its custom headers, WITHOUT reissuing its signing secret. Rotating a gateway credential should not force a redeploy of your signature verification — deleting and re-registering would, because a new endpoint gets a new secret. Send `events`, `headers`, or both; anything you leave out is untouched. Sending neither is `nothing_to_update` (400).\n\nRequired scope: `webhooks.manage`.", "body": { "mode": "raw", "raw": "{\n \"headers\": [\n {\n \"name\": \"X-Api-Key\",\n \"value\": \"the rotated value\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Edit an endpoint — 200", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/webhooks/:id", "host": [ "{{base_url}}" ], "path": [ "v1", "webhooks", ":id" ], "query": [] }, "description": "Change what an endpoint subscribes to, or replace its custom headers, WITHOUT reissuing its signing secret. Rotating a gateway credential should not force a redeploy of your signature verification — deleting and re-registering would, because a new endpoint gets a new secret. Send `events`, `headers`, or both; anything you leave out is untouched. Sending neither is `nothing_to_update` (400).\n\nRequired scope: `webhooks.manage`.", "body": { "mode": "raw", "raw": "{\n \"headers\": [\n {\n \"name\": \"X-Api-Key\",\n \"value\": \"the rotated value\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": 1,\n \"url\": \"https://erp.example.com/hooks/biklo\",\n \"events\": [\n \"order.created\"\n ],\n \"is_active\": true,\n \"consecutive_failures\": 0,\n \"disabled_at\": null,\n \"headers\": [\n {\n \"name\": \"X-Api-Key\",\n \"preview\": \"the ••••••••\"\n }\n ],\n \"secret_prefix\": \"whsec_64Ky4…\",\n \"created_at\": \"2026-09-21T09:14:03Z\"\n}" } ] } ] } ] }