Shipments & Returns

General

Learn how to create a new shipment and a return in Admin API.

For managing shipping in the SCAYLE Panel, see Checkout Customization.

Order Fulfillment

There three types of updates under order fulfillment:

Shipments
Cancellations
Returns

Shipping options

The following shop shipping option is created for the new shop:

Attribute	Value
Carrier	default
Shipping Method	Standard Delivery
Shipping Cost	0
Free shipping cost from	0

VAT for shipping cost

VAT for shipping costs is added to the order at checkout. VAT for shipping costs in Germany is calculated based on the VAT rate of the goods ordered.

Goods VAT	Shipping cost VAT
19%	19%
7%	7%

Calculate VAT for shipping cost

Calculation of the tax rate depends on the tenant configuration, either fixed ( 19%) or based on the product's tax rate.

Tenant configuration	Tax rate
`shipping.cost.tax.calculation.use.country.tax`	fixed tax rate = 19%
`shipping.cost.tax.calculation.use.country.tax`	tax rate is calculated depending on each product tax rate

Details of product net price calculation

productNetPrice = round(productBruttoPrice / (1 + productTaxRateAsDecimal)) // e.g round(1500 / (1 + 0.190)) for 19% tax
  + productBruttoPrice    -> Order_Product.product_price                // e.g 1500 (in cents)
  + productTaxRate        -> Order_Product.tax                          // e.g. 19
  + productTaxRateAsDecimal -> round(taxRate / 100, 3)                  // e.g round (19 / 100, 3) = 0.190

Details of tax rate calculation:

totalNetBasketValue = Sum (productNetPrices)

  calculatedTaxRate = 0.0
  
  for every product:
      basketShare = productNetPrice / totalNetBasketValue
      calculatedTaxRate = calculatedRate + basketShare * productTaxAsDecimal
  endfor

  finalTaxRate = round(calculatedTaxRate, 3) // float value with 3 decimals

This method is used to create a new shipment. When we have a success response it will mark product items as invoiced. The main difference between Create shipment and Create a Cancellation is that it marks deliverable item to true. Admin API order-invoiced

Method Signature

adminApi.apis.Fulfillment.createShipment({}, {requestBody: shipment});

Details

The company id is important to have the right configuration for the tenant. The company ID ensures proper tenant configuration.

Parameter	Type
shopKey	string
countryCode	string
carrier	string
deliveryDate	string
items	`ShipmentOrderItem`
orderId	integer
returnIdentCode	string
shipmentKey	string

Create a Shipment request

let shipment = {
     shopKey: "ms",
     countryCode: "DE",
     carrier: "HERMES_KLV",
     deliveryDate: "2022-09-23T11:30:58+00:00",
     items: [
        {
          orderItemId: 67219436,
          returnKey: "rtrn-NIS3534001000003"
        }
     ],
     orderId: "ayou-139-73",
     returnIdentCode: "rtrn-73-1",
     shipmentKey: "582301b967d97"
};

let parameters = {requestBody: shipment};

// only required when multiple companies are used
parameters.requestInterceptor = (req) => {
    req.headers["X-Company-Id"] = 1;
    return req;
};
adminApi.apis.Fulfillment.createShipment({}, parameters);

Create a cancellation

SCAYLE allows you to trigger a cancellation for any number of order items.

This method is used to create a cancellation request. All items are marked as not deliverable when we use the cancellation request Admin API

adminApi.apis.Cancellations.sendCancellation({}, {requestBody: cancellation});

If there are multiple companies in the system, it is required to provide a company ID

Properties

Param Name	Type	Required	Description
shopKey	string	true	A key that uniquely identifies the shop within the tenant's ecosystem. Must be exactly 2 chars long.
countryCode	string	true	ISO 3166-alpha 2 country code.
items	`CancellationItem`	true	Collection of items requested for cancellation.
orderId	integer	true	Unique identity of the order for which the cancellation was requested.

Send a cancellation request

let cancellation = {
    shopKey: "ms",
    countryCode: "DE",
    items: [
      {
        orderItemId: 67
      },
      {
        orderItemId: 72
      }
    ],
    orderId: 123
  };

let parameters = {requestBody: cancellation};

// only required when multiple companies are used
parameters.requestInterceptor = (req) => {
    req.headers["X-Company-Id"] = 1;
    return req;
};

adminApi.apis.Fulfillment.sendCancellation({}, parameters);

Return items

SCAYLE allows you to return multiple items.

This method is used to return multiple items. The returned items, should be shipped from Shipment, before that. It will create a refund for the order and it will send shipment return email confirmation. Admin API order-item-returned

adminApi.apis.Fulfillment.returnItems({}, {requestBody: returnItems});

If there are several companies involved, you need to give a company ID

Parameters

Parameter	Type	Required	Description
received	string	true	Timestamp when the product return is received.
returnKey	string	true	A key that is assigned to uniquely identify a return request.
returnReason	string	false	Description of why the return is initiated.

Create a Return Request

let returnItems = [
    {
         received: "2021-11-09 07:30:27",
         returnKey: "ayou-139-13376599_48_1",
         returnReason: "cci-manual-return"
    },
    {
         received: "2021-11-09 07:30:27",
         returnKey: "ayou-139-13376599_48_1",
         returnReason: "cci-manual-return"
    }
];

let parameters = {requestBody: returnItems};

// only required when multiple companies are used
parameters.requestInterceptor = (req) => {
    req.headers["X-Company-Id"] = 1;
    return req;
};

adminApi.apis.Fulfillment.returnItems({}, parameters);