Authentication
Similar to the Pull API, the Push API uses Basic Authentication. The information required consists of the username and password for your organization (image showing the use-case from Postman below).
Endpoints
Orders
1.1. Push orders consolidated
In the past, the API has supported individual endpoints for pushing orders, customers, and products. Having a single endpoint for pushing the entire structure ensures better data consistency, making it also easier for the customer to push the full payload, instead of performing separate calls for the required entities.
The purpose of the endpoint is to push orders (including the customer and product data) that can then be further returned by customers in the Returns portal based on the return policy setup in the portal.
URL: POST /push-orders-consolidated
Push order Test environment:
https://staging.returnado.com/public-api/v3/push-api/push-orders-consolidated
Push order Prod environment:
https://new-prod.returnado.com/public-api/v3/push-api/push-orders-consolidated
Parameters:
There are no query string or URL parameters, but the method requires the caller to send an array of PushOrderConsolidated models in the body of the request.
The properties that are possible on the input JSON are detailed below, split by the sub-objects that they are representative of:
Example call:
Request Body:
[
{
"orderId": "mircea-test-2",
"marketCode": "root",
"currency": "SEK",
"customerId": "bc-test-customer-1",
"createdAt": "2023-01-20T18:54:11.627+01:00[UTC]",
"updatedAt": "2023-01-22T18:54:11.627+01:00[UTC]",
"netTotal": 27,
"taxTotal": 5,
"grossTotal": 32.0,
"items": [
{
"orderItemId": "sku-1",
"nonReturnable": false,
"netAmount": 8.5,
"taxAmount": 2.5,
"grossAmount": 11.0,
"statusOfDelivery": "DELIVERED",
"countryOfOrigin": "USA",
"productVariant": {
"thumbnailImage": "http://123.com/image.1.jpg",
"images": [],
"name": "Sofa ordinary in red color",
"sku": "sofa-1-2-3",
"attributes": [
{
"name": "size",
"value": "XL"
},
{
"name": "color",
"value": "red"
}
],
"ean": "1233578",
"harmCode": "09887676",
"countryOfOrigin": "USA",
"weightValue": 24,
"weightUnits": "kg",
"customsArticleDescription": "a huge nice red sofa",
"variantId": "internal-variant-id-1",
"productId": "sofa-1-2-3",
"productName": "Sofa ordinary",
"productSku": "sofa-1-2",
"productDescription": "Sofa ordinary"
}
}
],
"customer": {
"customerId": "bc-test-customer-1",
"firstName": "John",
"lastName": "Doe",
"email": "mircea@test.com",
"phoneNumber": "+1000",
"locale": "en",
"deliveryAddress": {
"name": "John Doe",
"streetAddress": "Street 1 4",
"city": "Big Apple",
"state": "Massa",
"country": "Happyville",
"postalCode": "12345"
}
}
}
]
Order object:
Property | Type | Required | Additional Info |
orderId | string | Yes | |
alternativeOrderIds | string[] | No | |
marketCode | string | Yes | Used to specify the desired market for the given order. The Returns platform support multiple markets (when needing different currencies etc.) |
currency | string | No | |
customer | Customer | Yes | Model described below |
createdAt | DateTime (ISO Format) | No | Populated automatically with current DateTime if not submitted |
updatedAt | DateTime (ISO Format) | No | Populated automatically with current DateTime if not submitted |
netTotal | decimal | No | Net cost of the order |
taxTotal | decimal | No | Tax amount of the order |
grossTotal | decimal | No | Amount of order including taxes |
items | OrderItem[] | Yes | Model detailed below |
shipmentDate | DateTime (ISO Format) | No | Date of shipment |
shippingCostTotal | decimal | No | Used when refunding shipping cost |
shippingAddress | Address | No | Model detailed below |
invoiceExternalId | string | No | External id of the invoice in case you need a special id registered together with the order) |
isHidden | boolean | No | Defaulted to false |
isNonReturnable | boolean | No | Defaulted to false (if true makes all order items non-returnable) |
isPending | boolean | No | Used for setting the order in a pending state meaning it’s not processed fully yet, so it’s not available for return until this is set to false. |
isCancelled | boolean | No | Flag to indicate the order is cancelled and no return is allowed. |
Order Item object:
Property | Type | Required | Additional Info |
orderItemId | string | No | Identifier of order item in external e-commerce system |
nonReturnable | boolean | No |
→ if order level nonReturnable is set to true, this is cascaded to all OrderItems → the property at OrderItem level can be used to set only specific items from the order as nonReturnable |
netAmount | decimal | No | Net cost of the order item |
taxAmount | decimal | No | Tax amount of the order item |
grossAmount | decimal | No | Amount of order item including taxes |
statusOfDelivery | string/enum | Yes | Possible values are: “DELIVERED”, “PENDING”. The value added here determines whether the item can be returned, only items that are already “DELIVERED” can be returned. |
quantity | int | No | Set to 1 automatically if nothing specified, needs to be a value >1 and <99 |
hsCode | string | No | |
countryOfOrigin | string | No | |
customsDescription | string | No | Description to be used for customs declaration |
ean | string | No | |
productVariant | ProductVariant | Yes | Model detailed below |
ProductVariant object:
Property | Type | Required | Additional Info |
thumbnailImage | string | No | URL to image that should be displayed as a thumbnail for the respective product variant |
images | string[] | No | Array of images characteristic of the product variant |
name | string | No | Human readable name of the product variant |
sku | string | No | Identifier of the specific product variant in the external e-commerce system |
attributes | Dictionary<string, string> | No | Dictionary containing key value pairs, having a “name” and a “value”, with attributes describing the product variant |
ean | string | No | |
harmCode | string | No | |
countryOfOrigin | string | No | |
weightValue | double | No | Value of weight of the productVariant |
weightUnits | string | No | Measurement unit of the weight (such as kg) |
customsArticleDescription | string | No | Description of the given product which is sent through for booking with carriers when it’s cross border and customs information is needed. |
variantId | string | No | Variant Id in the external e-commerce system |
productId | string | No | |
productName | string | Yes | Name of the product variant |
productSku | string | No | Sku of the product |
productDescription | string | No |
Customer object:
Property | Type | Required | Additional Info |
customerId | string | Yes | Identifier of customer in external e-commerce system |
firstName | string | No | |
lastName | string | No | |
string | No | ||
phoneNumber | string | No | |
locale | string | No | |
deliveryAddress | Address | No | Model detailed below |
createdAt | DateTime (ISO Format) | No | Populated automatically with current DateTime if not submitted |
updatedAt | DateTime (ISO Format) | No | Populated automatically with current DateTime if not submitted |
Address object:
Property | Type | Required | Additional Info |
name | string | No | |
streetAddress | string | Yes | |
city | string | No | |
state | string | No | |
country | string | No | Filled from countryAlpha2 on order level if empty on Address level |
postalCode | string | No |