docs
  1. SCAYLE Resource Center
  2. Onboarding Guide
  3. Onboarding: Backend
  4. Send Order Updates

Send Order Updates

You’re almost done! In this final section, we’ll teach you all about the order updates you can send via the Admin API.

Order updates in SCAYLE

After receiving an order in your system, you can send these types of order updates via the Admin API, which are reflected in the data retrieved by APIs can trigger:

  • transactional mails
  • payment operations like capturing or refunding
  • webhooks
  • invoices

It is completely optional to send order updates. However, if you require features of SCAYLE to be triggered (see above), you should consider sending them.

In order to update orders, you use following methods:

EndpointDescription
Create ShipmentUsed to notify SCAYLE, about items, which were shipped (usually physically shipped).
Create CancellationUsed to notify SCAYLE, about items, which cannot be fulfilled.
Create ReturnUsed to notify SCAYLE, about items, which were returned by the customer.

What else to consider when sending order updates

  • When you have an order with multiple items and you send them out physically in a package, each package should be represented by one create-shipment request.
  • The property shipmentKey can be used to send the track & trace id along with the request, which can be retrieved in the Frontend using the Customer Account API in order to generate the tracking url, see getApiCustomerOrder.
  • You’ll need the returnKey set via the create-shipment endpoint to send returns, so you should use a retrievable identifier. We recommend using the same orderItemId as the returnKey when sending shipments if you don’t need a different key. By doing this, you do not have to continue using the returnKey because the orderItemId should work anyways.
  • A cancellation can be sent whenever an order item cannot be fulfilled. Cancellations can be sent independently from the current order item state. For example, if an order item was already shipped, it can also be canceled afterward. The same applies to returns.
  • One cancellation request can contain particular order items or all order items of one order.

Sending order updates for Fashion Store

In the last chapter, we already received our first order in the German shop.

Now let’s assume the order has been physically fulfilled and one package was shipped via DHL. In this case, you would send out the following shipment:

{
  "shopKey": "fs",
  "countryCode": "DE",
  "carrier": "DHL",
  "deliveryDate": "2023-11-08 14:30:27",
  "items": [
    {
      "orderItemId": 1,
      "returnKey": "550357807160"
    }
  ],
  "orderId": 123,
  "returnIdentCode": "123456789012",
  "shipmentKey": "582301b967d97"
}
ParameterDescription
shopKeyMust match the shopKey, where the order was initially placed in. See shopCountry.shopKey in the order-confirmed webhook.
countryCodeMust match the countryCode, where the order was initially placed in. See shopCountry.countryCode in the order-confirmed webhook.
carrierThe carrier the order was sent out with.
deliveryDateDefines the timestamp of the package leaving the warehouse.
items.orderItemIdCorresponds to the id of the order item received within the order-confirmed webhook and identifies an order line item uniquely.
items.returnKeyUsed to map future return requests to the corresponding order line item.
orderIdCorresponds to the id received within the order-confirmed webhook and uniquely identifies an order.
returnIdentCodeUnique ID generated for product return (in case the customer prefers to return the product later).
shipmentKeyA key that is assigned to uniquely identify a shipment. For example, the track&trace of the carrier.

Unfortunately, the customer decided to return the item, so we assume that the return was processed. In that case, we need to send the order update to SCAYLE using the following operation create return:

[
    {
        "received": "2023-11-09 07:30:27",
        "returnKey": "550357807160"
    }
]
ParameterDescription
receivedThe property defines the date the return was physically received.
returnKeyThe value must match the returnKey set within the previous shipment request.

That’s it! You successfully updated your first order and made it through the guide.

Further education - SCAYLE Academy

Wrapping Up

Congratulations! You’ve learned how to configure and integrate the basic features and endpoints necessary to run an eCommerce business in SCAYLE.

There are many more features and APIs to discover, so feel free to consult the following resources:

Previous
Get Ready to Receive Orders
Next up
Introduction