What changes

• POST /v1/returns/{id}/accept changed behaviour. It used to refund the buyer for the whole order at once, whether or not the parcel had come back. Now it works only while the inspection is open — the parcel delivered to you, before inspection.deadline_at — and refunds the price of the returned lines. Otherwise 409: return_not_delivered, return_not_open, inspection_deadline_passed or return_decision_failed. It still takes the order id and returns the order. Orders paid before Biklo Payments behave as before.
• New POST /v1/returns/{id}/reject with a reason (10–2000 characters): opens a dispute; the Biklo team refunds in full, refunds part, or refunds nothing.
• GET /v1/returns gained return_order_id, reference, inspection (status, delivered_at, deadline_at, refund, refunded, decided_at, decided_by, can_accept, can_reject) and items (the returned lines with return_status).
• New webhooks, each with the same payload as an item of GET /v1/returns:
  • return.delivered — the parcel is back with you; decide before deadline_at.
  • return.escalated — the Biklo team decides now (you rejected it, or the deadline passed).
  • return.resolved — decided: accepted, partially_refunded or rejected (no refund).
• GET /v1/wallet/lots gained held_for_return; is_withdrawable is now false while a return holds the order's money.

If you subscribed to every event (an empty events list), the new webhooks arrive without any change on your side.

What changes

• New size query parameter: a6, a5, a4 or original.
• Default: the size the seller chose in their Biklo settings, and A6 if they never chose. Until now you always received the courier's own PDF — usually an A4 sheet with the label printed twice. If your printing is set up for A4, send size=original (unchanged output) or size=a4.
• One parcel per page. Each distinct label is cut out and placed on its own portrait page; the duplicate copy couriers print on the same sheet is dropped, and every parcel of a multi-parcel order is kept.
• A4 and A5 print at real size (never enlarged); A6 fills the page.
• X-Label-Size response header with the size actually served. It reads original while label formatting is switched off on Biklo's side.
• An unknown size is 400 invalid_size. size does not apply to format=zpl.

Orders

• Short shipment on accept. POST /v1/orders/{id}/accept takes items: [{id, quantity}] when you have fewer pieces than were ordered. The courier is booked for those; only once it returned an AWB is the line reduced and the buyer refunded the missing pieces' product price. A failed booking changes nothing.
• Order lines carry quantity (ships), quantity_ordered and quantity_short.
• refunded on every order and refunds on GET /v1/orders/{id}: what went back to the buyer and why (short_shipped, buyer_returned, …). total stays what was paid.
• Packing: a line's pieces can be split across boxes — never more boxes than pieces (it used to be "never more boxes than lines").

Webhooks

• order.created is sent once the order's lines exist and now includes items. It used to arrive a moment before them, so a fast GET could find no items.
• New order.items_changed after a short shipment, with every line and the refund.
• A sell-out sends product.sold. When Biklo orders take the last pieces you get product.stock_changed (to 0) then product.sold — it used to say product.archived.

Products

• Restocking relists. A listing Biklo orders sold out comes back on sale when you send stock above 0 (PATCH /v1/products/{id}/stock or a full update). No unarchive needed.
• unarchive answers product_reserved (409) only for a listing with no stock left while an order for it is in progress — never for a listing that still has stock.

Why

Accepting an order books the courier, and the courier reports the parcel's progress itself. A "handed to the courier" signal from you added nothing: no pickup, no money and no message depended on it. It moved the order to ship_to_courier without checking where the order was, so calling it late could pull a delivered order backwards.

What changes for you

• The order stays accepted after you hand the parcel over, and through delivery.
• Where the parcel is: GET /v1/orders/{id}/tracking — status is the courier's latest status, events[].is_final marks the delivery. The order also carries delivered_at.
• The PHP SDK marks orders()->confirmShipped() @deprecated, and the WooCommerce plugin drops its "Confirm handed to courier" button.

Sandbox: POST /v1/sandbox/orders/{id}/advance

• accepted is still the order's own step. picked_up, in_delivery and delivered are now courier steps: they book the sandbox courier if nobody has, add courier events (Picked-Up, Out for Delivery, Delivered) to the AWB's tracking, and leave the order accepted. Before, they changed the order status to picked_up / in_delivery / delivered, which production never does.
• delivered stamps delivered_at and starts the return window, as a real delivery does. settled is unchanged.
• ship_to_courier is gone (see the confirm-shipped deprecation). A step behind the current one answers already_past.
• Jumping ahead still works in one call (pending → delivered accepts on the way and writes the courier steps in between).

delivered_at on every order

GET /v1/orders now carries delivered_at on each order, not only GET /v1/orders/{id}. status stays accepted through delivery, so this is how a poll sees the parcel arrived — a delivery also bumps updated_at, so ?updated_since= picks it up.

Why

The order status stays accepted while the parcel travels and after it is delivered: courier scans record the delivery (delivered_at on the order) but do not change the order status. So a delivered parcel answered "status": "accepted" on its own tracking endpoint.

What changes for you

{
  "order_id": 610,
  "status": "Delivered",
  "internal_status": "accepted",
  "awb": { "number": "95328086", "tracking_url": "https://track.innoship.io/..." },
  "events": [ … ]
}

• status — the latest courier event's status, or null until the courier has reported anything. It is the courier's text, so to know the parcel arrived use events[].is_final, not a match on the wording.
• internal_status — what status used to be: the order status, same vocabulary as GET /v1/orders/{id}.
• GET /v1/orders and GET /v1/orders/{id} are unchanged, including the ?status= filter.

If you read status from this endpoint, read internal_status instead.

What was wrong

Accept only changed the order's status. The order then sat "accepted" with no courier. An AWB requested afterwards with POST /v1/orders/{id}/awb was booked, but stored without the tracking record courier updates are matched against — so the parcel's progress never reached Biklo: no delivery, no confirmation, and no payout.

What changes for you

• Call accept as before. Read the AWB from its response (awb.number, awb.tracking_url) and fetch the label from GET /v1/orders/{id}/label.
• If the courier cannot be booked, accept fails and the order stays pending — retry once the reason is fixed: courier_required (422), buyer_phone_missing (422, the buyer has been asked to add one), awb_generation_failed (502).
• POST /v1/orders/{id}/awb still works and is idempotent: it returns the AWB accept booked.

Orders accepted through the API before this change were repaired on our side: the ones without a courier have one now, and every AWB is tracked.

images in POST /v1/products, PUT and the batch

A product's image URLs can now travel with the product:

{ "external_id": "ERP-1001", "…": "…",
  "images": ["https://cdn.example.com/erp/mtb-front.jpg"] }

Until now images needed their own call per product, so the first sync of a 2 000-product catalogue was two batches plus 2 000 image requests — most of a day's rate limit. With images in the payload it is two batches.

The rules are the ones attributes already has: sent, the list replaces the listing's images (an identical list changes nothing, so a re-push does not churn them); omitted, they are left alone. Every entry must be an http(s) URL — a bad one is invalid_image_url naming its position, rather than being dropped and the listing published with an image missing. At most 20 per product.

POST /v1/products/{id}/images stays, for multipart uploads.

POST /v1/products/{id}/archive and /unarchive

Setting stock to 0 never took a product off the marketplace: the listing stayed visible, just unbuyable. Archiving does — out of search, the storefront and carts — the same way the seller's own "disable ad" does, so a Biklo order cancelled later does not republish it. unarchive puts it back on sale — including a product a Biklo order marked sold, once that order is delivered — and is refused with product_reserved (409) only while an order for the product is still in progress.

Both are idempotent and need products.write.

Sandbox orders fire your webhooks

An event caused by your own API call is not sent back to you — a catalogue sync does not want a delivery for every product it just wrote. That rule also swallowed the events from POST /v1/sandbox/orders and POST /v1/sandbox/orders/{id}/advance, so the one tool meant for testing webhook handling produced no webhooks.

The sandbox helpers stand in for a buyer and a courier, so their events are now delivered to you: create a test order and order.created arrives; advance it and order.status_changed follows.

Relisting a product a Biklo order sold

A Biklo order marks its products sold and archives them — one sale, one listing. POST /v1/products/{id}/unarchive puts such a product back on sale once its order is delivered. It is refused with product_reserved (409) only while an order for the product is still in progress; a cancelled or rejected order republishes the product by itself.

curl https://api.biklo.com/v1/orders/711/customer -H "Authorization: Bearer $KEY"

{
  "id": 9000001,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+40700000000",
  "billing": {
    "address_line": "Str. Exemplu 12",
    "city": "Brasov",
    "county": "Brasov",
    "postal_code": "500002",
    "country_code": "RO",
    "country": "România",
    "is_company": true,
    "company": {
      "name": "Example Bike Shop SRL",
      "vat_code": "RO12345678",
      "registration_no": "J16/123/2020"
    },
    "is_live": true,
    "delivered_to_locker": false
  }
}

Three endpoints:

• GET /v1/orders/{id}/customer — the buyer as they were for that sale. This is the one to call when you are about to invoice: a customer who has moved has two orders at two addresses, and each invoice carries its own.
• GET /v1/customers — everyone who has bought from you, with their latest billing details. Paginated, filterable on updated_since and searchable on name or email.
• GET /v1/customers/{id} — one buyer plus every order they placed with you, each flagged has_invoice. has_invoice: false is your queue of orders still to bill.

is_company is the field to branch on

A buyer who checked out with a company address must be invoiced as that company, with its CUI — not as the person. Read the flag; do not infer it from whether company came back populated.

A new scope, off by default

These sit behind customers.read, which is not part of orders.read. An order carries a delivery address because you cannot ship without one. A full postal address, an email and a company's fiscal identity is a different thing to hand out, and a stock-sync integration has no use for it. Sellers grant it under "Customers and invoicing" in their dashboard.

One caveat worth reading

is_live: true means address_line was read from an address the buyer still controls and can edit. Only the city, county, postcode and country were frozen at checkout. If your invoices have to be reproducible, store the billing block at the moment you issue the invoice rather than re-fetching it later.

Where a buyer has since deleted that address, address_line is null and is_live is false — the rest of the block still stands.

The new events

Products — product.created, product.updated, product.stock_changed, product.price_changed, product.sold, product.archived, product.deleted.

Variant groups — product_group.created, product_group.updated, product_group.deleted, keyed by your external_group_id.

Orders — order.awb_created (the waybill, with its number and tracking URL) and order.tracking_updated (one per courier scan).

Everything else — question.answered, company.updated, company.bands_updated, invoice.issued.

Every one is listed with its exact payload in the event reference.

We no longer send you your own changes

A change your integration made through the API is not delivered back to you. You already know about it, and on a nightly catalogue sync it was thousands of deliveries telling you what you had just done.

It still reaches the seller's other integrations — a stock feed and an accounting system both connected will each hear about the other's writes — and anything changed in the Biklo dashboard reaches everyone.

You do not need to do anything. If you were filtering out your own writes at your end, you can stop.

One product edit is one event

A write that touches several columns does not send several deliveries:

1. A lifecycle change wins outright — deleted, archived, sold, approved, rejected — and nothing else is sent.
2. Otherwise stock and price are announced, and both can fire.
3. Otherwise a single product.updated naming what moved.

So a sync that changes a title and the stock sends product.stock_changed only, not that plus an updated.

Two things to know before you subscribe to everything

order.tracking_updated is the highest-volume event here — a parcel produces several scans and every shipment in flight is polled. If you only want to know it arrived, subscribe and filter on is_final; you keep the audit trail and lose nothing.

notification.sent is the next highest: one delivery per email and SMS we send about your orders.

Both are genuinely useful. Neither is something to switch on without meaning to.

Smaller things in the same release

Returns are identifiable. A return is an order in its own right, so it always emitted order.status_changed — you just could not tell it apart from a normal order. Every order event now carries is_return, and a return also carries parent_order_id.

payout.updated gained needs_review, for a payout that failed and is waiting on a person.

product.price_changed is in minor units, like every other amount in this API. posts stores price in major units internally; the event does not leak that.

POST /v1/webhooks

{
  "url": "https://gateway.example.com/biklo/webhooks",
  "headers": [
    { "name": "X-Api-Key", "value": "the value your gateway expects" }
  ]
}

Up to five per endpoint. Values are stored encrypted, never returned and never written to a delivery record — GET /v1/webhooks shows the name and the first four characters so you can tell two credentials apart.

Rotating one no longer costs you your signing secret

PUT /v1/webhooks/{id} is new. It edits an endpoint in place:

PUT /v1/webhooks/42

{ "headers": [ { "name": "X-Api-Key", "value": "the rotated value" } ] }

It also takes events, so narrowing or widening a subscription no longer means deleting and re-registering. Neither touches the signing secret, which was the real cost of the old approach: rotating a gateway credential meant a new endpoint, a new secret, and a deploy of your verification code for a change that had nothing to do with signing.

headers replaces the whole set rather than merging — we cannot show you what is stored, so there is nothing sensible to merge into. An empty list clears them.

It is not authentication

A fixed header value says nothing about the body it arrived with. It gets our request past your gateway; X-Biklo-Signature is what tells you the payload is ours and unmodified. Verify it either way.

Also fixed

The reference for POST /v1/webhooks said an empty events list "subscribes to nothing, so the endpoint is registered and silent". It has always meant the opposite — an empty list subscribes to every event, including ones added later, and that is what the page says now. Nothing about the behaviour changed.

What changed

When you create or update a product without a city_id, the listing takes the city, county and street of the seller's default shipping address.

It used to take the city of the company's registered address, and failing that the city of any listing the seller already had. Meanwhile the parcel's origin was built from the default shipping address — a different row, which can name a different county. A seller whose warehouse was not their registered office published a catalogue that said Cluj while every waybill was raised in Ilfov, and nothing reconciled the two.

The street is new as well: partner-written listings carried no address text at all.

It is re-read on every write

Not copied once at creation. A stock-only PUT re-syncs the location, so a seller who changes their default address sees their catalogue follow on the next push, and listings created before this rule repair themselves the first time you touch them.

This is the same self-healing behaviour ship_with_us already had.

city_id still overrides, for a real second location

Send city_id (and optionally county_id) when the item genuinely ships from somewhere else. The override sets the city and county and deliberately leaves the street empty — putting the default address's street under a different city would name a place that does not exist.

If you have been sending city_id on every product out of habit, stop. You will get a more accurate listing by leaving it out.

Addresses are now part of the API

Shipped in the same release: /v1/addresses — list, create, update, delete, and POST /v1/addresses/{id}/default. Under the Company profile permission group, so an existing key with company write access already has it.

curl -X POST https://api.biklo.com/v1/addresses \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"city_id": 1, "street": "Bulevardul Decebal 14", "postal_code": "200001"}'

Your first address becomes the default automatically. GET /v1/addresses is worth making the first call of your setup routine: an account with no address publishes a perfectly valid catalogue and then cannot fulfil a single order, and nothing warns you until the first real sale.

Two deletes are refused on purpose. 409 last_address when it is your only one, and 409 default_address when it is the default and you have others — in both cases removing it would leave future orders with no origin while your listings stayed up.

Two things the endpoint decides for you: addresses are always company addresses, and they never modify your company profile. If you need to change the company's registered details, that is PUT /v1/company.

If the account still has no address, creating a product falls back to the company city or an existing listing as before, and the error now names what is actually missing rather than asking for a city_id.

POST /v1/webhooks/{id}/test

curl -X POST https://sandbox-api.biklo.com/v1/webhooks/1/test -H "Authorization: Bearer $KEY"

Queues a test.ping to that endpoint. Every other event needs something to happen first, which made "is my receiver wired up correctly?" a question you could only answer by creating a real order.

It travels the same path as a real event — same queue, same headers, same HMAC signature — so a delivery that arrives and verifies here proves the real ones will. It is sent regardless of what the endpoint subscribes to, because an integrator testing a receiver has not necessarily decided which events they want yet; test.ping is not itself subscribable, so you will never get one you did not ask for.

202 means queued, not delivered. The outcome appears on GET /v1/webhooks/{id}/deliveries a moment later. A switched-off endpoint is refused with 409 endpoint_disabled rather than silently accepting.

The webhooks guide now has a Testing before you go live section, including the three things worth deliberately breaking before you trust your receiver: a wrong secret, a 500, and a slow reply.

GET /v1/me now tells you whether you can ship

{
  "shipping_address": {
    "ready": false,
    "reason": "no_address",
    "message": "This account has no shipping address, so orders have nowhere to ship from. Create one with POST /v1/addresses.",
    "default_address": null,
    "details_url": "/v1/addresses"
  }
}

/v1/me is the first call every integration makes, and this is the failure that is hardest to see coming: products publish perfectly well without an address, look correct in the dashboard, and then the first real order has nowhere to ship from.

Deliberately not scope-gated, unlike the payout summary next to it. The integration that most needs this is the catalog-only one — it publishes, sees nothing wrong, and has no orders endpoint to discover the problem through.

Check shipping_address.ready on startup. If it is false, POST /v1/addresses is one call away.

shipping.ship_with_us is always on, and no longer yours to set

Every listing created through this API ships with Biklo. We quote the courier, the buyer pays delivery at checkout, and we book the waybill.

It used to default to false and honour whatever the payload said. That meant an ERP which simply omitted the shipping object published a catalogue nobody could order from — the listings looked fine, and nothing in the response said why no orders arrived. There was never a good reason to switch it off, because a listing a courier cannot be booked for is unbuyable here.

Sending ship_with_us still succeeds; it is ignored. You can drop it from your payload. A listing that somehow has it off is repaired by the next write.

The field is still returned, and is still worth reading: an older listing created in the dashboard can read false until it is next written through this API.

external_id is required

It is the only thing tying a listing here back to a row in your system, and it is what a repeated push matches on. Without it, a retry after a timeout creates a second listing instead of updating the first — and you have no way to find either.

It was optional, which made the safe path the one you had to know about. Now the safe path is the only one.

This matters most on POST /v1/products/batch: a retried batch without it would duplicate every product in it.

stock is required

Send 0 for something you are out of — that is a real answer and it is accepted. The field is rejected only if it is negative or not a number (invalid_stock).

Previously a create could omit it and the listing carried no stock figure at all, which is not a state worth being able to reach.

PATCH /v1/products/{id}/stock is still the cheaper way to move it afterwards.

Corrections to the documentation, not to the API

Separately, a large number of response examples were wrong — they showed two to four fields where the endpoint returns the whole object. POST /v1/products, PUT /v1/products/{id} and both PATCH routes all return the complete product, and always did. PUT /v1/company/shipping-absorption documented country_id and min_amount_cents, which no response has ever contained.

Every endpoint now documents every field it returns, with its type and meaning. If you built against an example rather than against what came back, it is worth a second look.

New

GET /v1/invoices

The fee invoices issued to you. One covers several orders, because liabilities are raised per order and invoiced in batches at settlement.

GET /v1/invoices/{number}/pdf

Raw PDF bytes — what your accountant files. Pass series when a number is ambiguous; a number is only unique within its series.

GET /v1/fee-liabilities

What is owed per order, including before an invoice exists — which is most of a current month.

Two fields worth reading carefully

owed_amount and charged_amount are not the same number. A liability can settle partially, so reading one and assuming the other is how books stop balancing.

written_off_amount is what Biklo gave up when the absorbed fees exceeded the order itself. You were never charged it. It appears because it happened, and your reconciliation has to account for the difference.

In the sandbox

Invoices are generated in code — nothing reaches our fiscal provider. They carry an SBX_ series, are stamped NOT A FISCAL DOCUMENT, and is_sandbox is true so you never have to infer it from the prefix. The PDF is real and downloadable, so you can build the filing side of your integration against it.

New

GET /v1/notifications

Every message the platform sent about your orders. Scoped by seller, not by recipient: most of this mail goes to buyers, so filtering on "addressed to you" would show you almost nothing of your own orders.

GET /v1/notifications?order_id=721&channel=mail

GET /v1/notifications/{id}

Adds the recipient and the rendered body.

The notification.sent webhook

Subscribe rather than poll. Thin, like every other event here — ids and a status, with the content behind the endpoint above:

{
  "type": "notification.sent",
  "data": {
    "notification_id": 7,
    "channel": "mail",
    "status": "suppressed",
    "template": "email_shipping_sent",
    "order_id": 721
  }
}

The one field to read carefully

status: suppressed is the sandbox's normal state. The message was composed in full and deliberately not delivered. It is not sent, and treating it as such would have you waiting on mail that was never going to arrive.

In production the same rows carry sent or failed — and only metadata, because a rendered order email carries the buyer's name, address and phone. body_available tells you which you are looking at.

Breaking

PUT /v1/company/shipping-absorption requires parcel_tier

Absorption used to be one promise per destination. It is now one per destination and parcel size, because the two are not remotely the same purchase: on RO→HU the courier charges about 26 RON for a small parcel and 539 for a large one.

{
  "country_code": "RO",
  "parcel_tier": "large",
  "currency": "RON",
  "bands": [
    { "min_amount": 0, "max_amount": 150000, "absorbs": false },
    { "min_amount": 150000, "max_amount": null, "absorbs": true }
  ]
}

Omitting it returns 400 parcel_tier_required. We made it required rather than defaulting to small on purpose — a default would have let you set bike thresholds while silently rewriting your accessory bands.

GET /v1/company/shipping-absorption returns one set per tier, and now uses min_amount / max_amount (it previously returned min_amount_cents / max_amount_cents, which you could not round-trip into the write).

New

GET /v1/products/{id}/pricing

What a buyer is charged, and what it costs you — from the same service that renders the product page, so you and your buyer never see different numbers.

Commission on every category

GET /v1/categories now carries commission per category, inherited down the tree. Set margins before listing instead of inferring the fee from a completed order. max_amount: null means uncapped.

Packing: parcels on accept

POST /v1/orders/{id}/accept takes an optional parcels array — which order lines go in which box. The courier prices per parcel, so three products declared as one box is one charge rather than three. Send nothing and one box per line is assumed, exactly as before.

Packing is merge-only: an order cannot ship in more boxes than it has lines.

Smaller additions

• GET /v1/orders/{id} returns parcels, and each order item now carries its id — that id is what a parcel plan references.
• Products carry a derived shipping_class and parcel_tier, so you can tell which of your two band sets governs a listing.
• GET /v1/wallet/balance gained settled_to_fees: terminal, where absorbed fees consumed the whole order. It was previously missing from the response entirely.
• GET /v1/wallet/lots gained net_transferred_amount — what actually reached the seller after absorbed fees were withheld. Reconcile against this, not amount.