Every order that you fulfill needs to be updated with shipping information. On every Order you can find an array that holds information about the ordered items. Each item has its own entry in this array, which we call order_items. Every order_item has its own STATE that you can update. You have to upload identifiers (e.g. IMEI or serial numbers), invoices, and tracking information. We offer two ways to handle shipments, either through your own shipping agreement or by using refurbed’s shipping agreement. If you work with your own shipping agreement(s), parcel tracking links must be set on every order_item individually which also allows the use of different carriers to fulfill an order. If you joined our shipping agreement, you can generate the shipping label for each order. Countries outside of the EU might require extra information for customs clearance.
All services and operations concerning shipping must be called with OrderItemService, OrderService, MerchantService, and ShippingProfileService in the URL followed by the command/operation.
E.g.:
https://api.refurbed.com/refb.merchant.v1.OrderItemService/UpdateOrderItem
or
https://api.refurbed.com/refb.merchant.v1.OrderService/CreateShippingLabel
or
https://api.refurbed.com/refb.merchant.v1.MerchantService/ListMerchantAddresses
or
https://api.refurbed.com/refb.merchant.v1.ShippingProfileService/CreateShippingProfile
All calls must be done using POST method.
Update (BatchUpdateOrderItems / BatchUpdateOrderItemsState / UpdateOrderItem / UpdateOrderItemsState)
We offer two endpoints (and their batch versions) that basically do the same with only one difference:BatchUpdateOrderItems and UpdateOrderItem can be used to update identifiers and/or parcel tracking links.BatchUpdateOrderItems**State** and UpdateOrderItems**State** can be used as above but additionally also set the order item state in one update call.
🗂️ States
Order states are a concept to organize your orders and keep track of them until they are shipped. Order states can’t be changed directly. You can only change the state of order_items (same state values as the order object). The order state is automatically calculated from the order_item states.
Order states are not shown to the customers and are only for your internal use. Order states are a good way to filter for new orders if you use order polling.
refurbed does not change order states automatically, triggered by any event or action e.g. you refund an order → state does not go to REJECTED. Also setting a state will not trigger any action or event e.g. setting the state to REJECTED → does not trigger a refund. refurbed only enforces state transitions as described below.
All orders are by default in state NEW. If you start fresh on refurbed we advise to start early using this feature. If you’re an existing seller, all your older orders are also in state NEW. It’s good to set all old orders to e.g. ACCEPTED or SHIPPED (if you can also provide a parcel tracking link), to be able to filter for all real new incoming orders.
Order item states
Can be changed. Change the order item state via BatchUpdateOrderItemsState / UpdateOrderItemState e.g. to ACCEPTED once you retrieved an order and checked your stock. Refer to the order_item_id. State value names are fix and cannot be changed.
| state | description | transition rules |
|---|---|---|
| NEW | Order item was not handled yet | Next states: REJECTED, CANCELLED or ACCEPTED |
| REJECTED | Order item cannot be fulfilled | Final state |
| CANCELLED | Order item was cancelled by the customer. It’s like REJECTED but was requested by the customer | Final state |
| ACCEPTED | Order item was accepted for fulfillment | Next states: CANCELLED or SHIPPED |
| SHIPPED | Order item was shipped. The parcel tracking link needs to be set for this state to be set. The item identifier should be set, if possible | Possible final state. Next possible state, if necessary: RETURNED |
| RETURNED | Order item was returned by the customer | Final state |
⚠️ Please always set the correct states for your order items in accordance with the transition rules. E.g. if your order item is in state NEW and you try to skip ACCEPTED by directly setting state SHIPPED it will create errors.
A good practice is to set the state of an order_item in accordance to some validation on your side e.g. stock. If stock is available set the state from NEW → ACCEPTED.
Order States
Cannot be changed, are calculated.
| state | description | calculation rule |
|---|---|---|
| NEW | Order was not handled yet | At least one order item has state NEW |
| REJECTED | Order was rejected (cannot be fulfilled) | All order items have state REJECTED |
| CANCELLED | Order was canceled | All order items have state CANCELLED |
| ACCEPTED | Order was accepted | At least one order item has state ACCEPTED, and none of the other items still have state NEW |
| SHIPPED | Order was fully shipped | All order items have state SHIPPED |
| RETURNED | Order was fully returned | All order items have state RETURNED |
Example of calculation
| calculated order state | order_item 0 state | order_item 1 state | order_item 2 state |
|---|---|---|---|
| NEW | NEW | NEW | NEW |
| NEW | NEW | ACCEPTED | SHIPPED |
| ACCEPTED | ACCEPTED | SHIPPED | SHIPPED |
📦 Parcel Tracking & Identifiers
Parcel Tracking Links and Identifiers are order item specific, so they must be set on every individual item. An update with parcel tracking link will trigger an email to the customer. The sending delay is 2 hours to allow you to update multiple links and we can group them to a single email (per order). If an order is older than 7 days it will not trigger this email anymore. You can either provide the tracking link or the tracking number and carrier name.
⚠️ Re-uploading tracking information will replace the previous uploaded tracking information. If you uploaded wrong tracking information you can re-upload the correct one and it will overwrite the previous data.
Update parcel tracking link and order_item state in one call
As soon as you receive/generated the tracking link from the carrier, send the tracking link and change the state to SHIPPED via BatchUpdateOrderItemsState / UpdateOrderItemState. Refer to the order item ID (id in the payload).
It is recommended to always update order item state and tracking link in one call, but you can also only update the order item with the tracking link by using UpdateOrderItem.
ℹ️ In order to ensure the utmost accuracy in assessing delivery timelines, we recommend uploading to the Merchant Interface the standard shipment tracking links from the carrier website. E.g.:
Carrier link: https://www.dhl.com/it-en/home/tracking/tracking-express.html?submit=1&tracking-id=<id>
By doing this, we can enhance the precision of your delivery performance metrics. Custom links from shipping platforms cannot ensure the accuracy of your delivery metrics.
Provide tracking number and carrier name
You can also opt to send the tracking_number and the carrier name instead of the full tracking link. Our integration partner AfterShip will then generate the tracking link. You can get a list of all available carriers with their name and slug by calling ShippingProfileService/ListAvailableCarriers. When specifying the carrier name please refer to the slug of the carrier. The AfterShip tracking link will then be sent to the customer and will also be visible on the order_item in the supplier interface.
If the tracking information that you provided was successfully parsed by AfterShip we will expose the parcel’s state in the order_item object. Two fields will be exposed: shipment_status and shipment_substatus.
Shipment status provides a high level information about the parcels state, while sub-status exposes more detailed information. You can find the values for each state here:
https://www.aftership.com/docs/tracking/enum/delivery-statuses (shipment_status)
https://www.aftership.com/docs/tracking/enum/delivery-sub-statuses (shipment_substatus)
⚠️ The parcel_tracking_number and parcel_tracking_carrier fields will be deprecated and removed at the beginning of May 2026.
Identifiers
You can assign an identifier to each order item, such as an IMEI (for smartphones, tablets, and smartwatches) or serial number (for other product categories). This helps identify the shipped item in case of a return. In the item_identifiers array, specify the identifier_type (IMEI or SERIAL_NUMBER) and its value. One identifier of each type can be added per order item. IMEI upload is mandatory and IMEI numbers have to be between 14-16 digits.
Use UpdateOrderItem to update only the identifier, or use UpdateOrderItemState to update the identifier, state, and parcel tracking link in one call.
⚠️The item_identifier field will be deprecated and removed at the beginning of June 2026.
🧾 Invoices (SetOrderInvoiceStream / GetOrderInvoice / DeleteOrderInvoice)
Upload invoice
You must issue an invoice to the customer for every order. For orders shipped to Switzerland, please use UploadOrderCommercialInvoice to upload the invoice.
If the purchased offer is marginally taxed, you must explicitly state on the invoice that the purchase is made under marginal taxation.
For orders from Portugal, customers can include their NIF number, a personal tax identifier for individuals in Portugal. If a customer provides their NIF during purchase, you can find it as personal_vatin within the shipping_address and invoice_address in the order object. Make sure to include it on the invoice.
If an order is invoicable you can upload an invoice by calling SetOrderInvoiceStream. Specify in the request body the order_id and the Base64 encoded invoice data. In the response to SetOrderInvoiceStream the URL to the invoice will be returned. Only one invoice can be uploaded per order. Refurbed will store the invoice and make it available to download in the customer’s account.
⚠️ File data must be in PDF format. Max file size is 1MB. Orders are invoiceable for 30 days.
⚠️ Make sure to retry failed invoice upload attempts in a reasonable frequency. If an invoice is already existing, the upload will succeed without overwriting the previously uploaded invoice.
⚠️ For details on the mandatory invoice upload penalty criteria, please refer to the Invoice Upload penalty criteria section.
Get invoice URL
You can check if an invoice has already been set when retrieving an order (ListOrders / GetOrder) by referring to the bool field "has_invoice" in the order object.
To retrieve the URL of the uploaded invoice, call GetOrderInvoice. The URL is available for 24 hours after upload. If expired, you can call again GetOrderInvoice to generate a new URL.
Delete invoice
If you want to delete an invoice you can call DeleteOrderInvoice and refer to the oder_id. After deletion, the invoice will be removed from the order in the customer’s account.
🇨🇭 Switzerland extra-EU delivery requirements
To enable international shipping from EU to Switzerland, additional information must be provided for parcels to successfully pass customs controls. The following fields are mandatory for Swiss shipments.
| Field | Type | Level | Description |
|---|---|---|---|
| Commercial invoice number | String | Order | Commercial invoice number. Must match what reported in the commercial invoice. It is the unique ID of the commercial invoice. |
| Commercial Invoice | File | Order | It's the primary document used by customs officials in the destination country to determine the applicable import duties, taxes, and regulatory controls. |
| Order item weight | Number | Order Item | Weight of each order item, comprehensive of all the included add-ons (plug, etc…). This information will be pre-filled by refurbed as the sum of standard values at item category level, with the option to override when necessary. |
| HS Code | String | Order Item | Harmonized System Code is a standardized numerical classification system used by international customs when importing products into a country. This information will usually be pre-filled by refurbed with standard values at item category level, with the option to override if wrong or not existing. |
| Country of manufacturing | ISO country code | Order Item | Country where the product was manufactured. This information will be pre-filled by refurbed with “China” (being the most common value), with the option to override when necessary. |
Get order information
Fetch order information using the existing APIs (Orders ). Use this step to verify that all required extra-EU information is filled.
Check if the default HS code, item weight and country of manufacturing are correct
- If it isn't, correct them (by updating the order item)
- If there is no HS code, provide one (by updating the order item)
Update Order Item Information (UpdateOrderItems / UpdateOrderItemsState / BatchUpdateOrderItems / BatchUpdateOrderItemsState)
This step allows modification of prefilled information for HS codes, country of manufacturing, and individual item weights.
{
"id": "string",
"parcel_tracking_url": "string",
"item_identifier": "string",
"parcel_tracking_number": "string",
"parcel_tracking_carrier": "string",
"weight_kg": 0, // CH field
"manufacturing_country": "UNSPECIFIED", // CH field, ISO format
"hs_code": "string" // CH field
}
Upload customs information (UploadOrderCommercialInvoice / GetOrderCommercialInvoice / DeleteOrderCommercialInvoice)
Customs information is mandatory for extra-EU shipments. The invoice must comply with formal invoicing criteria and must include the Swiss VAT. Provide the Commercial invoice number and commercial invoice file (base64 format) using UploadOrderCommercialInvoice .
You can retrieve the invoice when needed with GetOrderCommercialInvoice .
The commercial invoice will also be available for customers in their reserved area, allowing them to access this document independently.
If the wrong invoice was uploaded, you can delete it with DeleteOrderCommercialInvoice and re-upload the correct invoice before you generate the shipping label.
Generate shipping label
🏷️ Shipping label generation
If you joined or are planning to join our shipping agreement, you can also benefit from the automatic shipping label generation available in the merchant API. This allows you to generate the shipping label for your orders, while the tracking link will be automatically added to your orders.
⚠️ You can find more information about our shipping agreement here: Shipping . If you are interested in the automatic label creation feature, please contact your Account Manager to enable it for your account.
1. Add your addresses (MerchantService/CreateMerchantAddress)
If you (or the account manager) haven’t already, you must register your address(es) from where you send your parcels by calling CreateMerchantAddress. Each address gets a unique ID. This merchant_address_id is necessary to generate the shipping label as it indicates the departure address of the parcel. You can list your existing addresses and their ID’s by calling ListMerchantAddresses.
Please make sure to select the correct address! If the address from where you send the parcels is missing or has changed, please update or create it before generating the shipping label (UpdateMerchantAddress / CreateMerchantAddress). Unused addresses can be deleted by calling DeleteMerchantAddress.
2. Generate shipping label (OrderService/CreateShippingLabel)
Once you have received confirmation that the label creation has been enabled for your account, as well as you’ve completed the previous two steps, you can start generating shipping labels for your orders. Call OrderService/CreateShippingLabel and specify the merchant_address_id from where you are going to ship the parcel, the order_id, parcel_weight in kg which is the total weight of the whole parcel, and carrier. In the response, you will receive the shipping label for normal printers as well as label printers together with the tracking link, carrier name, and tracking number. The label URLs are PDF files and are valid for 1 hour. If you need to retrieve the label URL again you can call ListShippingLabels by indicating the order_id.
⚠️ Please note that each call to CreateShippingLabel creates a new label. The tracking link of the most recently created label will be shown to the customer.
⚠️ Currently, the only carrier option available is DHL_EXPRESS.
ℹ️ Upon label generation, the tracking link will be automatically added to the order. No need to send the tracking link or carrier data separately.
Limitations
The shipping label cannot be generated if an order contains items with different shipping profiles.
Shipping label generation is currently not available for all countries. More information here: DHL Express Rates Outbound Shipping Rates
Update Shipping Label Address (OrderService/UpdateShippingLabelAddress )
If the shipping label cannot be generated because of address issues, you can either cancel the order and ask the customer to place a new order using the correct address details or you can update the shipping label address by calling OrderService/UpdateShippingLabelAddress.
The functionality is available for both outbound and return shipments. The updated address is used exclusively for shipping label generation and does not overwrite the original customer address. The original address remains the source of truth for invoicing, compliance, traceability, and customer-related records.
Important
Changing the shipping label address can invalidate Klarna and PayPal fraud protection. Both payment providers require proof that the shipment was delivered to the address approved at the time of purchase.
By updating the shipping label address, you accept the risk that a future dispute may result in a chargeback from the payment provider.
Please also note:
- The original customer address is never modified
- It is not possible to change the original country