Push API – nShift

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"
            }
        }
    }
  ]

For an up-to-date list of fields and API information, please see our technical documentation here.

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
email	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

nShift Help Center