External Orders

The External Orders Import Endpoint

https://{BASE_URL}/imports/external_orders?...&stock_location={STOCK_LOCATION}

All import integration endpoints use the same authentication parameters, please see Authentication page for more details.

In addition to this the external orders endpoint also requires you to specify a stock location when creating an external order.

Since the nature of external orders are event-like, they cannot be undone by deleting them.

It is currently not possible to update an external order after creation.

Queueing one or more external orders for import requires you to send a HTTP POST request with the above parameters. The Content-Type should be application/json.

The body of the request must contain one or more external orders. You can queue as many external orders as you would like (at least one).

Upon success a HTTP 200 OK reponse will be given with body looking something like this:

{
    "status": "OK",
    "message": "Import of 1 external order(s) initiated"
}

In general the endpoint reponse will let you know if any of the external orders posted was not queued for import. It will also (if possible) let you know which of the actually failed.

Minimum external order import body

A minimum external order must have an order_identifier that must be unique across all external orders on the given stock location and a basket. A minimum basket must have a currency and a non-empty array of line_items.

{
    "external_orders": [
        {
            "order_identifier": "AKGJTHE",
            "basket": {
                "currency": "DKK",
                "line_items": [
                    {
                        "product_identifier": "KGJFITK",
                        "name": "Shiny product",
                        "quantity": 1,
                        "price": 10
                    }
                ]
            }
        }
    ]
}

Full external order import body

{
    "external_orders": [
        {
            "order_identifier": "AKGJTHE",
            "customer": {
                "customer_identifier": "FKSOEKD",
                "name": "Jane Doe"
            },
            "basket": {
                "currency": "DKK",
                "discounts": [
                    {
                        "type": "percentage",
                        "amount": 0.05,
                        "name": "5% off entire purchase"
                    }
                ],
                "line_items": [
                    {
                        "product_identifier": "KGJFITK",
                        "name": "One product",
                        "quantity": 1,
                        "price": 10
                    },
                    {
                        "product_identifier": "GJKRIGJ",
                        "name": "Other product",
                        "quantity": 10,
                        "price": 50,
                        "discounts": [
                            {
                                "type": "amount_per_item",
                                "amount": 5,
                                "name": "5 DKK off every item"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

Models

Order

order_identifier must be a string that is unique across all external orders for the given stock location.

basket must be a basket, see Basket for more information.

customer is an optional Customer, see Customer for more information

{
    "order_identifier": "FHGJRIL",
    "basket": {},
    "customer": {}
}

Basket

currency must be the ISO4217 currency representation for the basket. See Wikipedia article on the subject for more information.

line_items must be a non-empty array of line items.

discounts is an optional array of discounts applied to the entire basket. See Discount for more information.

{
    "currency": "DKK",
    "line_items": [],
    "discounts": []
}

Customer

customer_identifier must be a string.

name is an optional string. This is user facing.

{
    "customer_identifier": "NGJFITK",
    "name": "Lisa Kaching"
}

LineItem

product_identifier must be a string.

variant_identifier is an optional string.

barcode is an optional string.

image_url is an optional URL string pointing to a png or a jpg image. Please make sure that the server adheres to the Apple App Transport Security specification

name must be a string. This is user facing.

quantity must be a positive integer.

price must be a positive float.

discounts is an optional array of discounts applied to this line item. See Discount for more information.

{
    "product_identifier": "GJFIKEL",
    "variant_identifier": "DKFJIAL",
    "barcode": "9876483763526",
    "image_url": "https://some.url/image",
    "name": "Your new shiny product",
    "quantity": 2,
    "price": 10,
    "discounts": []
}

Discount

A discount can be applied to a line item and/or a basket.

name must be a string and is shown to the user.

type must be one of the possible DiscountType values mentioned below.

amount must be a number, if type is percentage it must be between 0 and 1 for the corresponding percentage.

Example of a discount:

{
    "name": "20% discount",
    "type": "percentage",
    "amount": 0.2
}

DiscountType

Can be one of the following:

  • amount - amount off on all items of a line item or a basket
  • amount_per_item - amount off per item of a line item, not usable on a basket
  • percentage - percentage discount on line item or a basket
  • new_price - new price for all items of a line item, or a basket
  • new_price_per_item - new price per item of a line item, not usable on a basket