docs
  1. Scayle Developer Guides
  2. Transactions & Orders
  3. Manage Transactions

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

ParameterDetails
with

String

Allows to load the following nested resources within this request:

  • legacyCustomData
  • items.legacyCustomData
  • customer.legacyCustomData
ParameterDetails
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

detailedStatusOrderDetailedStatus
vouchers

OrderVoucher[]

Applicable voucher and its details

loyaltyCardOrderLoyaltyCard

Examples

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

For security reasons, this method is disabled by default and restricted by IP address. Please approach the respective SCAYLE Account Manager for activation.

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 SCAYLE 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:

ParameterDetails
limit

Integer

Maximum number of items in the result. (default: 10, maximum: 100)

filters[id]

String

Comma-separated list of IDs of entities that should be used for filtering.

filters[referenceKey]String
Comma separated list of reference keys of orders
filters[minId]

Integer

Minimum (inclusive) ID of entities that should be returned.

filters[maxId]Integer
Maximum (inclusive) ID of entities that should be returned.
filters[minCreatedAt]

String

Minimum (inclusive) creation date of order that should be returned.

filters[maxCreatedAt]

String

Maximum (inclusive) creation date of orders that should be returned.

filters[minUpdatedAt]

String

Minimum (inclusive) modification date of orders that should be returned.

filters[maxUpdatedAt]

String

Maximum (inclusive) modification date of orders that should be returned.

filters[status]

String

Status of the orders. Supported values are: "order_open", "payment_pending", "payment_reserved", "invoice_completed", "cancellation_pending", "cancellation_completed", "invoice_partially_completed"

filters[detailedStatus]

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[billingAddressCountryCode]

String

Only returns orders with the given billingAddress country code (ISO 3166-1 alpha-3).

filters[shippingAddressCountryCode]

String

Only returns orders with the given shippingAddress country code (ISO 3166-1 alpha-3).

filters[customerId]

String

Comma separated list of customer IDs to return the orders for.

filters[minCustomerId]

Integer

Minimum (inclusive) customer ID of entities that should be returned.

filters[maxCustomerId]

Integer

Maximum (inclusive) customer ID of entities that should be returned.

filters[customerReferenceKey]

String

Comma separated list of reference keys of customers.

filters[firstName]String
Only returns orders belonging to a customer with the exact first name. Required if lastName is set. Requires lastName to be set.
filters[lastName]String
Only returns orders belonging to a customer with the exact last name. Required if firstName is set. Requires firstName to be set.
filters[email]String
Only return orders belonging to a customer with the given email.
filters[minInvoicedAt]String
Only return orders with items invoiced at or after this value.
filters[maxInvoicedAt]String
Only return orders with items invoiced at or before this value.
filters[voucherCode]String
Only return orders for which the specified voucherCode has been used.
filters[productId]Integer
Only returns orders with the given orderProductId.
filters[variantId]Integer
Only returns orders with the given variantId.
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

ParameterDetails
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;
ParameterDetails
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}, {requestBody: 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}, {requestBody: 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"
    }
  ],
  "carrier": {
    "carrierKey": "dhl",
    "deliveryDate": {
      "maximum": "2025-01-09",
      "minimum": "2025-01-15"
    },
    "shippingPolicyKey": "standard_delivery"
  },
  "referenceKey": "abc0123"
}

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

Create or Update Order Legacy Custom Data

This method allows creating or updating custom data associated with an order. The legacyCustomData field is a flexible JSON object where users can define their own key-value pairs. However, certain keys are restricted and cannot be used.

Validations:

1. Key Restrictions:

The following keys CANNOT be used and will result in a validation error:

  • eligiblePromotionIds
  • loyaltyPointsUsed
  • hasReturnCosts
  • returnCostAmount
  • minBruttoOrderValueAfterReturns
  • configuration
  • taxRateTransactionId
  • score
  • fees
  • originDevice
  • userAgent
  • bankReminderEmailCount
  • bankReminderSmsCount
  • isExpressCheckout

2. Payload Size:

The payload for customData shouldn't exceed 60 kb.\

Method Signature

await adminApi.apis.Orders.createOrUpdateOrderLegacyCustomData({shopKey, countryCode, orderId}, {requestBody: legacyCustomData});

Examples

const customData = {
  "key": "value"
}

await client.apis.Orders.createOrUpdateOrderLegacyCustomData({shopKey: "ms", countryCode: "DE", orderId: 123}, {requestBody: customData});

Create or Update Order Item Legacy Custom Data

This method allows creating or updating legacy custom data associated with an order item. The legacyCustomData field is a flexible JSON object where users can define their own key-value pairs. However, certain keys are restricted and cannot be used.

Validations:

1. Key Restrictions:

The following keys CANNOT be used and will result in a validation error:

  • externalTax
  • externalTaxes

2. Payload Size:

The payload for customData shouldn't exceed 60 kb.

Method Signature

const response = await adminApi.apis.Orders.createOrUpdateOrderItemLegacyCustomData({shopKey, countryCode, orderId, orderItemId}, {requestBodu: legacyCustomData});
const orderItem = response.body;

Examples

const customData = {
  "key": "value"
}

const response = await client.apis.Orders.createOrUpdateOrderItemLegacyCustomData({shopKey: "ms", countryCode: "DE", orderId: 123, orderItemId: 456}, {requestBody: customData});
const orderItem  = response.body;

Get Order Invoices

This method can be used to get a collection of invoices for a given order, which can be requested per id or reference key.

Method Signature

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

Order Invoice Collection

ParameterDetails
entities

OrderInvoice

A collection of order invoices.

cursor

Cursor

An object containing information for use in pagination.

Order Invoice Entity

ParameterTypeDetails
idintegerPDF document id (different from invoice identifier)
createdAtstring

timestamp when the document was created.

format: YYYY-mm-ddTH:i:sZ

typestring

The only possible values are:

  • invoice
  • partial_invoice
  • corrective_invoice
  • merchant_invoice
  • merchant_partial_invoice
  • merchant_corrective_invoice
  • custom_corrective_invoice
  • historical_corrective_invoice
  • praz
  • shipment_return_document
invoice.numberinteger|nullInvoice identifier number
invoice.fullNumberstring|nullInvoice identifier number that customer views on Order page
availablebooleanIf set to true, the invoice is generated.

Examples

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

let orderInvoices = response.body.entities;

Get Order Invoice

This method can be used to download an invoice pdf document, using the documentid that can be retrieved from the Get Order Invoices endpoint response.

Method Signature

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

Examples

let response = await adminApi.apis.Orders.getOrderInvoice({
    shopKey: 'ms', 
    countryCode: 'DE', 
    orderIdentifier: "key=my-key",
    invoiceId: 345
});
Previous
Processing
Next up
Transactional Mails