Manage Transactions

Admin API

Get an order

This endpoint is not bound to a specific shop country; however, it still requires the shop country details, identified by the shopKey and countryCode, without filtering by the shop country.

This method allows including nested resources using the with parameter.

let response = await adminApi.apis.Orders.getOrder({shopKey: shopKey, countryCode: countryCode, orderIdentifier: orderIdentifier});
let order = response.body;

Options

Parameter	Details
with	String Allows to load the following nested resources within this request: legacyCustomData items.legacyCustomData customer.legacyCustomData

Parameter	Details
id	Integer READ-ONLY The ID of the order created
address	OrderAddress Billing and Shipping address of the customer
basketKey	String A key that uniquely identifies customer's cart
confirmedAt	String Timestamp when the order was confirmed
contacts	OrderContact[] Collection of contacts
cost	OrderCost Total cost of the order that includes tax, VAT, etc
currencyCode	String ISO 4217 currency code
customer	Customer Details about the customer account
shopCountry	ShopCountry Country of the shop as ISO 3166 alpha-2 country code
invoicedAt	String Timestamp when the invoice is sent
createdAt	String Timestamp when the order is created
updatedAt	String Timestamp when the order is updated
items	OrderItem[] Collection of items ordered
legacyCustomData	Array[] Custom data added to the order (legacy feature)
membershipDiscount	OrderMembershipDiscount Membership discount information
packages	OrderPackage[] Details for the package(s) part of the order
payment	OrderPayment[] Payment details
publicKey	String Public reference set by the client to display to customers in account areas and transactional emails.
referenceKey	String READ-ONLY External order reference set by the client to integrate a third party system.
shipping	OrderShipping Shipping details
status	String Status of the order e.g: invoice_completed
detailedStatus	OrderDetailedStatus
vouchers	OrderVoucher[] Applicable voucher and its details
loyaltyCard	OrderLoyaltyCard

Get by Reference Key

Get an order by reference key:

let response = await adminApi.apis.Orders.updateOrderReferenceKey({shopKey: shopKey, countryCode: countryCode, orderId: orderId}, {requestBody: orderReferenceKey});
let order = response.body;

Get with Legacy Custom Data

Get an order with legacy custom data:

let response = await adminApi.apis.Orders.getOrder({
    shopKey: 'ms',
    countryCode: 'DE',
    orderIdentifier: "key=my-key",
    with: 'legacyCustomData'
});

let order = response.body;

console.log(order.legacyCustomData);

Get a collection of orders

This endpoint is not bound to a specific shop country; however, it still requires the shop country details, identified by the shopKey and countryCode, without filtering by the shop country.

Learn how to retrieve a collection of orders.

You can also request several orders. We suggest to fine-tune your search, e.g., by combing filter logics and using pagination. As search results are paginated, you can set the amount of orders displayed per page.

This method can be used to get a collection of orders for any given shop and country.
It is possible to refine the search by applying filter options.

This method might be disabled by default.

Please approach the respective account manager for activation.

let response = await adminApi.apis.Orders.getOrders({shopKey: shopKey, countryCode: countryCode});
let orders = response.body.entities;

Options

The operation can be used with optional parameters - called options:

Parameter	Details
limit	Integer Maximum number of items in the result. (default: `10`, maximum: `100`)
filters	String Comma separated list of reference keys of orders.
filters	String Comma-separated list of order IDs that should be used for filtering.
filters	String Status of the orders. Supported values are: "order_open", "payment_pending", "payment_reserved", "invoice_completed", "cancellation_pending", "cancellation_completed", "invoice_partially_completed"
filters	String Detailed status of orders. The value must be prefixed with `billing`, `order` or `shipping`. Supported values are: "order.order_created", "order.order_open", "order.order_pended", "order.order_confirmed", "order.order_delegated", "order.order_shipped", "order.order_invoiced", "order.order_aborted", "order.order_cancelled", "shipping.shipping_open", "shipping.shipping_ordered", "shipping.shipping_delivered", "shipping.shipping_cancelled", "shipping.shipping_undeliverable", "shipping.shipping_partially_delivered", "billing.billing_open", "billing.billing_pending", "billing.billing_payment_pending", "billing.billing_completed", "billing.billing_payment_aborted", "billing.billing_payment_cancelled", "billing.billing_refunded", "billing.billing_denied".
filters	Integer Minimum (inclusive) order ID of entities that should be returned.
filters	Integer Maximum (inclusive) order ID of entities that should be returned.
filters	String Minimum (inclusive) creation date of order that should be returned.
filters	String Maximum (inclusive) creation date of orders that should be returned.
filters	String Minimum (inclusive) modification date of orders that should be returned.
filters	String Maximum (inclusive) modification date of orders that should be returned.
filters	String Only returns orders with the given billingAddress country code (ISO 3166-1 alpha-3).
filters	String Only returns orders with the given shippingAddress country code (ISO 3166-1 alpha-3).
filters	String Comma separated list of customer IDs to return the orders for.
filters	Integer Minimum (inclusive) customer ID of entities that should be returned.
filters	Integer Maximum (inclusive) customer ID of entities that should be returned.
filters	String Comma separated list of reference keys of customers.
sort	String Sort by the provided column. Available values: id (default), appId, customerId, createdAt, confirmedAt, updatedAt, paymentKey.
sortDir	String Defines the sorting order: ascending or descending. Available values: asc (default), desc.
with	String Allows to load the following nested resources within this request: legacyCustomData items.legacyCustomData customer.legacyCustomData

Parameter

Parameter	Details
entities	Order A collection of orders.
cursor	Cursor An object containing information for use in pagination.

Details

entities

Order

A collection of orders.

cursor

Cursor

An object containing information for use in pagination.

Examples

Read with Options

Get an Order filtered by CustomerIds

let response = await adminApi.apis.Orders.getOrders({
    shopKey: 'ms',
    countryCode: 'DEU',
    "filters[customerId]": "10,11,12"
});

let orders = response.body.entities;

orders.forEach(
    order => console.log(order.referenceKey)
);

Update order reference key

This method can be used to create or update an order reference key. The existing reference key will be updated in case if an order was already assigned a reference key.

let response = await adminApi.apis.Orders.updateOrderReferenceKey({shopKey: shopKey, countryCode: countryCode, orderId: orderId}, {requestBody: orderReferenceKey});
let order = response.body;

Parameter	Details
referenceKey	String External reference set by the client to integrate a third-party system.

Parameter

Details

referenceKey

String

External reference set by the client to integrate a third-party system.

Examples

let orderReferenceKey = {
    referenceKey: "my-key"
};

let response = await adminApi.apis.Orders.updateOrderReferenceKey({shopKey: 'ms', countryCode: 'DE', orderId: 1}, {requestBody: orderReferenceKey});
let order = response.body;

console.log(order.referenceKey);

Create Order

This method allows creating a new order.

Orders created by the method are not meant to be active in the system and can’t receive any updates from live systems. Reference key should indicate orderId in legacy system.

Method Signature

const response = await adminApi.apis.Orders.createOrder({shopKey: shopKey, countryCode: countryCode}, {requestBodu: order});
const order = response.body;

Examples

const order = {
  "id": 790,
  "address": {
    "billing": {
     "city": "Hamburg",
      "additional": "c/o AboutYou",
      "countryCode": "DEU",
      "houseNumber": "12",
      "isDefault": {
        "billing": false,
        "shipping": false
      },
      "recipient": {
        "firstName": "Anna",
        "gender": "m",
        "lastName": "Fohlmeister",
        "type": "personal"
      },
      "referenceKey": "InGidcPDmL8fGkv02a3sSAgAr7ySMBfa66iw4MriYgUNI3Boq369rBOZW3stlKLWSqIjB2dXCGNbCxoM5Xww4cI8cULUoGBFJHH0",
      "street": "Wolfgangsweg",
      "zipCode": "20459",
      "createdAt": "2018-11-29T05:20:13+01:00",
      "updatedAt": "2018-11-29T05:20:13+01:00"
    },
    "shipping": {
      "city": "Hamburg",
      "collectionPoint": {
        "customerKey": "bced-234-234",
        "description": "Pedro's Kiosk",
        "key": "12345-a",
        "type": "hermes_parcelshop"
      },
      "countryCode": "DEU",
      "houseNumber": "10",
      "isDefault": {
        "billing": false,
        "shipping": true
      },
      "recipient": {
        "firstName": "Anna",
        "gender": "m",
        "lastName": "Fohlmeister",
        "type": "personal"
      },
      "referenceKey": "InGidcPDmL8fGkv02a3sSAgAr7ySMBfa66iw4MriYgUNI3Boq369rBOZW3stlKLWSqIjB2dXCGNbCxoM5Xww4cI8cULUoGBFJHH0",
      "street": "Domstrasse",
      "zipCode": "20459",
      "createdAt": "2018-11-29T05:20:13+01:00",
      "updatedAt": "2018-11-29T05:20:13+01:00"
    }
  },
  "confirmedAt": "2018-01-20T11:30:15+00:00",
  "cost": {
    "appliedFees": [
      {
        "amount": {
          "withoutTax": 168,
          "withTax": 200
        },
        "category": "delivery",
        "option": "deliveryCosts",
        "tax": {
          "vat": {
            "amount": 32,
            "rate": 0.19
          }
        }
      }
    ],
    "appliedReductions": [
      {
        "amount": {
          "absoluteWithTax": 100,
          "relative": 0.5
        },
        "category": "voucher",
        "type": "absolute"
      }
    ],
    "withoutTax": 1168,
    "withTax": 1390
  },
  "currencyCode": "EUR",
  "legacyCustomData": {
    "score": {
      "generatedOn": "2018-05-20T19:45:15+00:00",
      "result": "green"
    }
  },
  "customer": {
    "referenceKey": "InGidcPDmL8fGkv02a3sSAgAr7ySMBfa66iw4MriYgUNI3Boq369rBOZW3stlKLWSqIjB2dXCGNbCxoM5Xww4cI8cULUoGBFJHH0"
  },
  "invoicedAt": "2018-01-22T11:30:15+00:00",
  "items": [
    {
      "availableQuantity": 20,
      "legacyCustomData": {
        "key": "value"
      },
      "deliveryForecast": {
        "subsequentDelivery": {
          "key": "christmas"
        }
      },
      "key": "ac834d23e689u678",
      "packageId": 1,
      "price": {
        "appliedReductions": [
          {
            "amount": {
              "absoluteWithTax": 100,
              "relative": 0.5
            },
            "category": "sale",
            "type": "relative"
          }
        ],
        "reference": {
          "size": "100",
          "unit": "ml",
          "withTax": 595
        },
        "tax": {
          "vat": {
            "amount": 190,
            "rate": 0.19
          }
        },
        "withoutTax": 1000,
        "withTax": 1190
      },
      "product": {
        "id": 4564545,
        "images": [
          {
            "hash": "9f6c628a98106dcce2bc5a4ac1de9c14"
          }
        ],
        "name": "Chelsea Boots",
      },
      "reservationKey": "6nq69bzzkd5xufxliwg8",
      "status": "available",
      "variant": {
        "id": 1234567,
        "referenceKey": "563843898",
        "stock": {
          "supplierId": 1
        },
      },
      "warehouseId": 12345,
      "createdAt": "2018-01-20T09:30:15+00:00",
      "updatedAt": "2018-01-20T09:30:15+00:00"
    }
  ],
  "packages": [
    {
      "id": 1,
      "carrierKey": "dhl",
      "deliveryDate": {
        "maximum": "2018-02-05",
        "minimum": "2018-02-02"
      },
      "deliveryStatus": "open",
      "shipmentKey": "shpmnt-61-1"
    }
  ],
  "payment": [
    {
      "amount": 1190,
      "data": {
        "CCBrand": "VISA",
        "CCExpiry": "202005",
        "IPCity": "charlottenburg",
        "IPLatitude": "52.5151",
        "IPLongitude": "13.3053",
        "IPState": "berlin",
        "IPZone": "276",
        "IPZoneA2": "de"
      },
      "key": "accounting",
      "transactionKey": "creditcard-abcde"
    }
  ],
  "publicKey": "666",
  "referenceKey": "InGidcPDmL8fGkv02a3sSAgAr7ySMBfa66iw4MriYgUNI3Boq369rBOZW3stlKLWSqIjB2dXCGNbCxoM5Xww4cI8cULUoGBFJUU2",
  "shipping": {
    "policy": "least_packages"
  },
  "status": "invoice_completed",
  "voucher": {
    "applicableItems": [
      {
        "isApplied": true,
        "key": "a87ff679a2f3e71d9181a67b7542122c"
      },
      {
        "isApplied": false,
        "key": "eccbc87e4b5ce2fe28308fd9f2a7baf3"
      }
    ],
    "code": "fashion2020",
    "type": "absolute",
    "value": 1000
  },
  "createdAt": "2018-01-20T09:30:15+00:00",
  "updatedAt": "2018-01-20T09:30:15+00:00"
}

const response  = await client.apis.Orders.createOrder({
    shopKey: 'ms',
    countryCode: 'DEU',
}, {
  requestBody: order,
});

const order = response.body;

Delete Order

This method allows you to delete an order by its ID or reference key.

Only orders created by the API can be deleted.

Method Signature

await adminApi.apis.Orders.deleteOrder({shopKey: shopKey, countryCode: countryCode, orderIdentifier: orderIdentifier});

Examples

// Delete by reference key
await client.apis.Orders.deleteOrder({
    shopKey: 'ms',
    countryCode: 'DEU',
    orderIdentifier: "key=my-key",
});

// Delete by id
await client.apis.Orders.deleteOrder({
    shopKey: 'ms',
    countryCode: 'DEU',
    orderIdentifier: 1,
});

Create Subscription Order

This method allows creating a new subscription order.

Method Signature

const response = await adminApi.apis.Orders.createSubscriptionOrder({shopKey: shopKey, countryCode: countryCode}, {requestBodu: subscriptionOrder});
const order = response.body;

Examples

const subscriptionOrder = {
  "address": {
    "billing": {
      "additional": "Test address",
      "city": "New York",
      "countryCode": "DEU",
      "firstName": "Michael",
      "gender": "m",
      "houseNumber": "1650",
      "lastName": "Jackson",
      "phone": "0049/1234567890",
      "street": "Bedford Ave",
      "zipCode": "11225"
    },
    "shipping": {
      "additional": "Test address",
      "city": "New York",
      "countryCode": "DEU",
      "firstName": "Michael",
      "gender": "m",
      "houseNumber": "1650",
      "lastName": "Jackson",
      "phone": "0049/1234567890",
      "street": "Bedford Ave",
      "zipCode": "11225"
    }
  },
  "legacyCustomData": {
    "basketId": "mop_basket_ID"
  },
  "customerId": 1263116,
  "ipAddress": "127.0.0.1",
  "items": [
    {
      "variantId": 46892617
    }
  ],
  "paymentTypes": [
    {
      "authorizedValue": 2990,
      "confirmationData": {
        "descriptor": "DG0452755Z3",
        "profileId": "ABOUTYOU_TE_DE",
        "subscriptionPaymentReference": "74-201507071360201",
        "transactionId": "74-201507071360201",
        "type": "accounting"
      },
      "transactionId": "74-201507071360201",
      "type": "accounting"
    }
  ]
}

const response  = await client.apis.Orders.createSubscriptionOrder({
    shopKey: 'ms',
    countryCode: 'DEU',
}, {
  requestBody: subscriptionOrder,
});
const order = response.body;