Orders include all the information related to the customer and the ordered goods. That includes the shipping and invoice address, the total order amount, commissions, the ordered items in the currency of the customer, and, if applicable, converted into the base currency of your bank account.

Every Order has an array that holds information about the ordered items. Every single ordered item has its own entry in this array. We refer to them as order_items. Every order_item has its own STATE and can be updated with identifiers (e.g. IMEI or serial numbers separately. Parcel tracking links must be set on every order_item individually which also allows the use of different carriers to fulfill an order. Order items can be different products, so in every order_item we include data of the original offer like the SKU, shipping profile ID, grade, and warranty.

All services and operations concerning orders must be called with OrderService or OrderItemService in the URL followed by the command/operation.

E.g.:
https://api.refurbed.com/refb.merchant.v1.OrderService/ListOrders

https://api.refurbed.com/refb.merchant.v1.OrderItemService/GetOrderItem

All calls must be done using POST method.

Read (`ListOrders` / `GetOrder` / `GetOrderItem` / `ListOrderItemsByOrder`)

📢 Order Notifications

We offer two ways to receive orders from refurbed. Both ways are legit and we let you decide what works best with your system. It is very important that you test order transmission very carefully. The transmission of orders must be fail-safe and reliably designed.

Order Polling

You can set up a worker to get new orders periodically with the endpoint OrderService/ListOrders. We advise you to choose a reasonable interval depending on your expected order volumes. Please also consider implementing a retry in case there is a networking issue. With the new API we introduced Order states and we advise you to use them to limit the number of results. Our suggestion is to filter for NEW orders and acknowledge new incoming orders by setting their order_item states to ACCEPTED. We provide a lot of filters and options to craft responses to your needs: Filters, Sorting, Pagination & Versioning.

Instant Order Notification (ION) Webhook

The alternate way is to let us inform you about new orders via webhook. For this, you need to set up a receiving end where we will send a POST requests as new orders arrive.
The setup of ION is described here

We will only send you the order_id, so to retrieve the full order information you need to call OrderService/GetOrder with the id in the request body.

📃 Order information

In the order response, you can find information to identify the order and its state, furthermore you find information about the customer, like shipping address and invoice address, many fields dedicated to pricing and refunds (please see below section). In the Items section, you will find all order item specific information like SKU, the unit's pricing, parcel tracking related fields as well as an offer_data section which exposes data from your offers like grading, shipping_profile and costs, taxation, or battery condition.

⚠️ In some cases we are unable to parse the house_no field from the customers input, therefore the house_no field stays empty. If that is the case, we recommend checking the supplement field and concatenate or extract the data from there.

👓 Order Items Handling

Get all order_item_ids of an order by calling OrderItemService/ListOrderItemsByOrder with the order_id in the request body. OrderItemService/GetOrderItem returns the data of a specific order_item that you specified by sending the order_item_id in the request body.

💶 Pricing

The total amount that the customer paid or was charged includes the shipping costs that you set in your shipping profile. The price the customer sees on the refurbed website is the sum of the offer price and the shipping costs. When retrieving an order you receive this total price including shipping costs in the response. The shipping costs themselves are listed separately in the offer_data in the Item section of an order . Please note that those shipping costs are always in the currency the customer paid in.

Regarding pricing information, we return two types of pricing information: Presentment and Settlement. Settlement indicates how the charge was settled with our payment provider, all fields are prefixed with settlement_. This depends on the bank accounts stored with your account in your onboarding process. If no bank account in the target currency is set to your account a 2.5% exchange rate modifier will also be applied to the price.
All fields that are NOT prefixed with settlement_ are presentment. All presentment fields show the value in the currency as it was shown to the customer on the public marketplace page.

In case of a discount, the discount amount is deducted from the total_charged price and is distributed proportionally on the items in the cart. The discounts are a collaborative marketing campaign between you and refurbed.

The fields exist in the order object as well as every single order_item object. In the order object, the values represent the sum of all order_items.

Field name	Description
currency_code	The presentment currency. This is the currency that is shown on the public page and thus what customer saw and paid.
settlement_currency_code	The currency the charge is settled in on Stripe or PayPal depending on the merchant's bank accounts (the charge is settled depending on what bank account the merchant has set) Since a EUR bank account is mandatory the current rule is: if merchant has bank account in presentment currency -> settlement = presentment if merchant doesn't have a bank account in presentment currency -> use default currency = EUR
total_charged	Amount that is charged from the customer in presentment currency. This value derives from offer_price (reference_min_price to reference_price) including shipping costs, dynamic pricing, and eventual taxes. If a discount (voucher) was redeemed, see `total_discount`, this amount is deducted.
settlement_total_charged	settlement_total_commission
total_charged_dynamic	The dynamic price part of the charged amount `total charged` + `total_discount` in presentment currency ("dynamic pricing").
settlement_total_charged_dynamic	The dynamic price part of the charged amount `settlement_total_charged` + `settlement_total_discount` converted into settlement currency ("dynamic pricing").
total_paid	Amount left after refunds. Sum of `total charged` + `total_discount` in presentment currency. If a refund is/was made, see `total_refunded`, it will be deducted from this amount.
settlement_total_paid	Amount left after refunds. Sum of `settlement_total_charged` + `settlement_total_discount` converted into settlement currency. If a refund is/was made, see `settlement_total_refunded`, it will be deducted from this amount in settlement currency.
total_refunded	The total amount the customer was refunded.
settlement_total_refunded	The total amount the customer was refunded, converted into settlement currency.
settlement_total_commission	Sum of all commissions, in settlement currency.
settlement_base_commission	Base commission based on a fixed percentage set on product category, converted into settlement currency.
settlement_payment_commission	Payment commission paid by the merchant, converted into settlement currency.
settlement_payout_commission	Commission for special payout routines (has to be requested at AM, standard is 0), converted into settlement currency.
settlement_dynamic_commission	Dynamic commission based on competition and market analyzing algorithms, converted into settlement currency.
total_discount	Discount (Voucher) in presentment currency. Voucher amounts are currently only in EUR.
settlement_total_discount	Discount (Voucher) in settlement currency. Voucher amounts are currently only in EUR.
offer_order_exchange_rate	Exchange rate applied to convert amounts from offer currency to order currency. E.g. if you have a SEK offer and a DK customer orders (in DKK).
settlement_exchange_rate	Exchange rate applied to convert amounts from presentment currency into settlement currency. E.g. If you have a DKK order but only a EUR bank account.

VAT

VAT and accounting-related information is available for each order.

The order object includes shipping_address and invoice_address fields that indicate whether the purchase is private or business. If entity is COMPANY, it's a business purchase and you'll find additional details like company_name and company_vatin in the address fields.

For orders from Portugal customers can also indicate their private VAT ID which you can find in the personal_vatin field.

Each order item includes taxation information showing whether the offer that was purchased is taxed as GROSS, MARGINAL, or NET.

Additionally, each order item includes these VAT-related fields:

vat_rate	Rate of the value-added tax (VAT) applied to the order item. Example: vat_rate = 20 stands for 20% VAT
vat_country	Alpha-2 country codes as specified in ISO 3166-1.
vat_charged	The amount of VAT the customer was charged for this item, in order currency.
settlement_vat_charged	The amount of VAT the customer was charged for this item, in settlement currency.

And the order object includes the total VAT charged across all items in presentment currency (total_vat_charged) and settlement currency (settlement_total_vat_charged).

Examples

Given the following conditions, order with one order_item, reference_currency EUR:

Initial offer settings

Min. Ref Price	unset
Reference Price	200 EUR
Shipping cost	0 EUR
Dynamic Pricing (not active)	0 EUR
Tax (MARGINAL)	0 EUR

→ 200 EUR is shown to the customer

"currency_code": "EUR",
"settlement_currency_code": "EUR",
"total_charged": "200.00",
"settlement_total_charged": "200.00",
"total_charged_dynamic": "0.00",
"settlement_total_charged_dynamic": "0.00",
"total_paid": "200.00",
"settlement_total_paid": "200.00",
"total_refunded": "0.00",
"settlement_total_refunded": "0.00"
[...]
"total_discount": "0.00"
"settlement_total_discount": "0.00"

On sale (with discount)

Voucher redeemed	50 EUR

"currency_code": "EUR",
"settlement_currency_code": "EUR",
"total_charged": "150.00",
"settlement_total_charged": "150.00",
"total_charged_dynamic": "0.00",
"settlement_total_charged_dynamic": "0.00",
"total_paid": "200.00",
"settlement_total_paid": "200.00",
"total_refunded": "0.00",
"settlement_total_refunded": "0.00"
[...]
"total_discount": "50.00"
"settlement_total_discount": "50.00"

After sale (with discount and refund)

Partial refund	100 EUR

"currency_code": "EUR",
"settlement_currency_code": "EUR",
"total_charged": "150.00",
"settlement_total_charged": "150.00",
"total_charged_dynamic": "0.00",
"settlement_total_charged_dynamic": "0.00",
"total_paid": "100.00",
"settlement_total_paid": "100.00",
"total_refunded": "100.00",
"settlement_total_refunded": "100.00"
[...]
"total_discount": "50.00"
"settlement_total_discount": "50.00"

Given the following conditions, PL customer buys on refurbed.pl, offer reference_currency EUR:

Offer settings

Offer Currency	EUR
Min. Ref Price	unset
Reference Price	200 EUR
Shipping cost	0 EUR
Dynamic Pricing (not active)	0 EUR
Bank account	EUR

Offer price will be converted to PLN:

offer_order_exchange_rate: 4.697374
exchange rate modifier: 1.025 (2.5%) because no PL bank account

→ 200 EUR * 4.698704 * 1.025 = 963.23 PLN is shown to the customer

"currency_code": "PLN",
"settlement_currency_code": "EUR",
"settlement_exchange_rate": "0.207634"
"total_charged": "963.23",
"settlement_total_charged": "200.00",
"total_charged_dynamic": "0.00",
"settlement_total_charged_dynamic": "0.00",
"total_paid": "963.23",
"settlement_total_paid": "200.00",
"total_refunded": "0.00",
"settlement_total_refunded": "0.00"
[...]
"total_discount": "0.00"
"settlement_total_discount": "0.00"
"offer_data": {
   [...]
   "offer_order_exchange_rate": "4.698704"
}

On sale (with discount)

Voucher	20 EUR (10%)

voucher can be redeemed directly in checkout, and will also be converted to PLN

20 EUR * 4.698704 * 1.025 = 96.32 PLN

→ 963.20 - 96.32 = 866.91 PLN is shown to the customer

"currency_code": "PLN",
"settlement_currency_code": "EUR",
"settlement_exchange_rate": "0.207634"
"total_charged": "866.91",
"settlement_total_charged": "180.00",
"total_charged_dynamic": "0.00",
"settlement_total_charged_dynamic": "0.00",
"total_paid": "963.20",
"settlement_total_paid": "200.00",
"total_refunded": "0.00",
"settlement_total_refunded": "0.00"
[...]
"total_discount": "96.32"
"settlement_total_discount": "20.00"
"offer_data": {
   [...]
   "offer_order_exchange_rate": "4.698704"
}