Orders API allows you to synchronize orders from your e-shop to Retino in real time. It's a modern alternative to the Retino XML feed – instead of periodic imports, you synchronize orders immediately when they are created.
Complete technical reference can be found in the API documentation.
🤔 When to use Orders API?
Before implementation, consider what type of synchronization you need:
Do you need Tracking with instant notifications?
✅ YES → Orders API (instant synchronization)
Order creation emails sent immediately
Real-time shipment tracking
Instant status updates
Webhook integration with e-shop
✅ NO → Retino XML Feed (synchronization up to 6 hours)
Simpler implementation (just expose XML feed URL)
Sufficient if you only use Returns
Customer cannot return goods within 6 hours after purchase
Suitable if you cannot call API from your system
Why use Orders API?
Instant synchronization – order is in Retino immediately after creation
Transactional emails – you can send order confirmations in real time
Current data – changes to the order are reflected immediately
Preparation
1. Create API Token
In Settings → API v2 create a new token. Use the token in the header of each request:
Authorization: your_api_token
2. Create Store ID
What is Store ID?
Store ID is a unique identifier of your e-shop in Retino. Together with the order number (code), it forms a unique key for each order.
Why is Store ID important?
Unique identification: The combination of
code+store_iduniquely identifies an orderAutomatic upsert: When the same combination is sent again, the order is updated instead of creating a duplicate
Multi-store support: You can have multiple e-shops under one Retino account
How to create Store ID:
Go to Settings → API v2
In the "Store IDs" section, click "Add Store ID"
Enter an identifier (e.g., "main-shop", "shop-uk")
Save and use this identifier in every API request
Important: Store ID cannot be changed after an order is created. Always use the same Store ID for all orders from one e-shop.
Typical use cases
Use Case 1: Webhook on order creation
Scenario: Customer completes a purchase in your e-shop and you want to send them a confirmation email immediately.
Solution:
Set up a webhook in your e-shop that triggers after order creation
Webhook sends the order to Retino using
POST /api/v2/ordersRetino creates the order and can send a confirmation email to the customer
Example request:
curl -X POST "https://app.retino.com/api/v2/orders" \ -H "Authorization: your_api_token" \ -H "Content-Type: application/json" \ -d '{ "code": "ORD-2025-001", "store_id": "main-shop", "order_date": "2025-10-23T14:00:00Z", "currency": "USD", "language": "en", "price": { "with_vat": "199.99" }, "customer": { "email": "[email protected]", "phone": "+1234567890" }, "shipping_address": { "name": "John Doe", "street": "Test Street", "house_number": "1", "city": "New York", "postal_code": "10001", "country": "US" }, "items": [ { "name": "Smartphone XY", "code": "PROD-001", "amount": "1.00", "item_type": "PRODUCT", "total_price": { "with_vat": "179.99" } }, { "name": "Shipping Fee", "item_type": "SHIPPING", "total_price": { "with_vat": "19.99" } } ] }'
Use Case 2: Status update on dispatch
Scenario: You have packed and shipped the order. You want to inform the customer about the shipment.
Solution:
Warehouse system marks the order as dispatched
Call the endpoint to change the status
Retino can send an email about the shipment
Example:
curl -X PATCH "https://app.retino.com/api/v2/orders/ORDER_UUID/status?status_value=DISPATCHED" \ -H "Authorization: your_api_token"
Use Case 3: Initial import of historical orders
Scenario: You have an existing e-shop with thousands of orders and want to transfer them to Retino.
Solution:
Export orders from the last 30 months from your e-shop
Split them into batches of max. 100 orders
Use the
POST /api/v2/orders/bulkendpoint to import each batch
Example:
curl -X POST "https://app.retino.com/api/v2/orders/bulk" \ -H "Authorization: your_api_token" \ -H "Content-Type: application/json" \ -d '[ { "code": "ORD-001", "store_id": "main-shop", "price": {"with_vat": "100.00"}, "customer": {"email": "[email protected]"} }, { "code": "ORD-002", "store_id": "main-shop", "price": {"with_vat": "200.00"}, "customer": {"email": "[email protected]"} } ]'
The API returns information about successfully processed and failed orders.
Use Case 4: Partial data update
Scenario: Customer changed their email or phone number and you want to update the order.
Solution:
Use PATCH /api/v2/orders/{id} and send only the fields that are changing:
curl -X PATCH "https://app.retino.com/api/v2/orders/ORDER_UUID" \ -H "Authorization: your_api_token" \ -H "Content-Type: application/json" \ -d '{ "customer": { "email": "[email protected]", "phone": "+9876543210" } }'
Other order data remains unchanged.
Order statuses
An order has two types of statuses. You can change them using the PATCH /api/v2/orders/{id}/status endpoint:
Status Type | Value | Meaning |
Processing |
| New order |
Processing |
| Picking |
Processing |
| Packed |
Processing |
| Dispatched |
Processing |
| On hold |
Processing |
| Ready for pickup |
Processing |
| Picked up |
Payment |
| Awaiting payment |
Payment |
| Paid |
Payment |
| Partially refunded |
Payment |
| Refunded |
Payment |
| Payment failed |
Automatic update vs. creation
Orders API automatically recognizes whether to create or update an order based on the combination of code + store_id:
First submission of order
ORD-001+main-shop→ new order is created (HTTP 201)Second submission of the same combination → existing order is updated (HTTP 200)
Thanks to this, you can use the same webhook for both creating and updating orders. You don't need to check if the order already exists.
Practical tips
Store ID naming
If you operate multiple e-shops or sales channels, create a separate Store ID for each:
shop-us– main US e-shopshop-uk– UK e-shopshopify-store– Shopify storeamazon-us– Amazon
Importance of customer email
The customer.email field is not required, but it is critical for transactional emails. Without an email, Retino cannot send the customer:
Order confirmation
Shipment notification
Delivery information
Correct item types
Distinguish item types for better overview:
PRODUCT– productsSHIPPING– shipping feeBILLING– payment feeDISCOUNT– discounts and coupons
Status history
You can send the entire order status history at once using the statuses field. This is useful during initial import:
"statuses": [ {"name": "PAID", "date": "2025-10-23T10:00:00Z"}, {"name": "PICKING", "date": "2025-10-23T12:00:00Z"}, {"name": "DISPATCHED", "date": "2025-10-23T15:00:00Z"}]
Common problems
Store ID does not exist
Error: "Store ID 'xyz' does not exist"
Solution: Create the Store ID in API settings before sending the first order.
Order is not being created, only updated
Reason: An order with this code + store_id already exists.
Solution: This is expected behavior. If you want to create a new order, use a different order number (code).
Price error
Error: "Price mismatch: 1000 + 210 ≠ 1200"
Solution: If you send all three price values (with_vat, without_vat, vat), they must be mathematically correct. You can send just one value and omit the others.
Technical documentation: app.retino.com/api/docs
API settings: app.retino.com/settings/api-v2/