A practical guide to the LionWheel delivery API for businesses and couriers: which token to use, the fields tasks/create requires, how to avoid duplicate deliveries with original_order_id, the numeric status codes, cash-on-delivery amounts in agorot, and status webhooks.
Key takeaways
- Every LionWheel call passes its token in a query parameter named key, over HTTPS with JSON bodies.
- A courier's token needs a company_id in the body; a business's own token starts with c_key and is linked to its courier automatically.
- original_order_id must be unique - look it up with tasks/by_order_id before creating, so a retry never ships twice.
- Dates are dd/mm/yyyy and money_collect is in agorot, so 150 shekels is 15000.
The LionWheel API lets a store, ERP or order system create delivery tasks in LionWheel automatically, instead of someone retyping each order. You send POST /api/v1/tasks/create to members.lionwheel.com with the destination address, recipient and phone, pass your token as the key query parameter, and get back a task id, a barcode, a printable label and a tracking link.
LionWheel is an Israeli delivery management platform used by courier companies and by businesses that run their own drivers. This guide is for the business or developer connecting orders to it, and covers the details that most often break the connection.
Which LionWheel token should you use?
LionWheel has two token types, and using the wrong one is the first error most integrations hit:
| Who you are | Where the token comes from | What the request must include |
|---|---|---|
| The courier company | Settings > API definition > API key | company_id of the business the delivery belongs to, from the top of that customer's settings page |
| A business that ships through a courier | Requested from the courier, who copies it from your customer page | Nothing extra - the task is linked to you and to the courier automatically. The token starts with c_key |
If you are a store connecting to your courier's LionWheel account, you want the second kind. A token that does not start with c_key was probably the courier's own key, and it needs a company_id on every call.
The fields tasks/create requires
The documentation marks these as mandatory:
pickup_at- the delivery date, in dd/mm/yyyy (defaults to today).original_order_id- your order number. It must be unique.destination_city,destination_street,destination_number- the address, as three separate fields.destination_recipient_nameanddestination_phone.
The optional fields cover most of what an Israeli delivery needs: destination_floor, destination_apartment, destination_entrance_code, a delivery time window with earliest and latest, packages_quantity, urgency (0 regular, 1 urgent, 2 super urgent), line_items with SKU and quantity, is_roundtrip, age_verification, and PDF, PNG or JPEG documents in Base64 - an invoice or a delivery note to hand over at the door.
Connecting orders to LionWheel, step by step
- Get the right token (see the table above) and ask LionWheel support for a test environment before touching production.
- Split the address in your order system into city, street and house number. A single address string does not map to the required fields.
- Before creating a task, call
GET /api/v1/tasks/by_order_id/{order_id}. If a task already exists for that order, do not create another. - Send
POST /api/v1/tasks/create?key=...with the order's fields. - Store the returned
task_id,public_idandtracking_linkon the order, and send the tracking link to the customer. - In LionWheel, open Organization > API settings, enter your webhook URL and choose the statuses to subscribe to.
- When a status arrives, update the order in your system - and alert someone on
FAILED.
For WooCommerce stores, LionWheel's help centre documents a ready-made connection, which is worth checking before writing code.
What do LionWheel's status numbers mean?
The status field on a task is an integer, and both tasks/show and the update call use the same codes:
| Code | Status |
|---|---|
| 0 | UNASSIGNED |
| 1 | ASSIGNED |
| 2 | ACTIVE |
| 3 | COMPLETED |
| 4 | CANCELED |
| 5 | ROUNDTRIP_DELIVERED |
| 6 / 7 | IN_INVENTORY / OUT_INVENTORY |
| 8 | FAILED |
| 9 | FINAL_FAILED |
| 10 | IN_TRANSFER |
Map these to your own order states in one place. FAILED (8) usually means another attempt is still possible, while FINAL_FAILED (9) means the delivery is over and the order needs a person. Treating them the same either refunds too early or never follows up.
What goes wrong in a LionWheel integration
- Cash on delivery in shekels instead of agorot.
money_collectis an integer in the smallest unit: 150 shekels is15000. Sending150tells the driver to collect 1.50. Setcod_typetoo: 0 cash, 1 cheque, 2 card, 3 bank transfer. - ISO dates.
2026-10-01is not01/10/2026. The API expects dd/mm/yyyy. - Duplicate deliveries on retry. A timeout does not mean the task was not created. Always check by order id before retrying.
- 401 versus 403. 401 is an authentication error - the key. 403 is what the documentation calls a data mismatch; a
company_idthat does not belong to the token is the first thing to check. - Phone formats. Store one normalised format, because
tasks/by_phone/{phone}searches by the exact string.
The wider question of which delivery layer to build on is covered in a delivery aggregator versus a direct courier API, and labels in automating shipping labels in Israel. Why deliveries fail and how to catch it early is in failed delivery reasons and controls.
What to have ready before you start
- The token, and a
company_idif it is a courier token. - Addresses stored as city, street and number, with floor and apartment where you have them.
- One phone format across the order system.
- A decision on which order event creates the delivery - payment, packing or a manual button.
- An HTTPS endpoint for status webhooks, and someone who is notified when a delivery fails.
Sources
Frequently asked questions
Does LionWheel have an API?
Yes. LionWheel publishes a REST API with JSON bodies at members.lionwheel.com/api/v1, documented on GitHub. It creates, reads and updates delivery tasks, looks tasks up by order id or phone, manages companies and daily driver routes, and sends status updates to a webhook you configure in the organization's API settings.
Which fields are required to create a LionWheel delivery?
pickup_at in dd/mm/yyyy, a unique original_order_id, destination_city, destination_street, destination_number, destination_recipient_name and destination_phone. A courier's own token also needs the company_id of the business the delivery belongs to. Everything else, such as floor, time window or packages, is optional.
How do I avoid creating the same delivery twice?
Use your order number as original_order_id, which LionWheel expects to be unique, and call GET /api/v1/tasks/by_order_id/{order_id} before every create or retry. A timeout does not prove the task was not created, so the lookup, not the error, decides whether to send it again.
How do I get delivery status updates from LionWheel?
In LionWheel's organization settings, on the API tab, enter a webhook URL and choose the statuses to subscribe to. LionWheel POSTs a payload with the same structure as the delivery creation call whenever a task reaches one of them. You can also poll GET /api/v1/tasks/show/{task_id} for a single task.
Why does LionWheel return 403?
The documentation describes 403 as a data mismatch error, while 401 is an authentication error. The first thing to check is a company_id the token is not allowed to use, which happens when a courier token and a customer c_key token are mixed up. Check which token type you hold first.
Keep reading
Related service
Integrations
Make the systems you already pay for talk to each other.
About the author
Yehonatan Saadia
Freelance automation, web & MVP developer
I'm Yehonatan Saadia, a senior developer who builds business automation, custom websites, and MVPs for small and mid-sized companies across the US, Europe, and Israel. These guides come from real client work, not theory.
Work with meHave a project like this?
Tell me what you're trying to automate or build. I reply within 24 business hours with a few targeted questions, then we walk through it on a free 30-minute call, with no commitment. You come away with a scope, a timeline and a fixed price - or a straight answer that it isn't worth building.