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 |
| 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% |
| 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 |
| 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
Details of tax rate calculation:
Admin API
Create a shipment
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.
When a shipment is created, the Admin API triggers the order-invoiced webhook.
Method Signature
Details
The company id is important to have the right configuration for the tenant. The company ID ensures proper tenant configuration.
This endpoint offers a fallback mechanism to overcome the shop countries limitation. When having multi-languages shop countries defined within the same shop, you can pass the shop country ID as countryCode.
| Parameter | Type |
|---|---|
| shopKey | string |
| countryCode | string |
| carrier | string |
| deliveryDate | string |
| items | ShipmentOrderItem |
| orderId | integer |
| returnIdentCode | string |
| shipmentKey | string |
| Parameter | Type |
|---|---|
| shopKey | string |
| countryCode | string |
| carrier | string |
| deliveryDate | string |
| items | ShipmentOrderItem |
| orderId | integer |
| returnIdentCode | string |
| shipmentKey | string |
Create a Shipment request
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.
When a cancellation is created, the Admin API triggers order-cancelled webhook event.
If there are multiple companies in the system, it is required to provide a company ID.
When having multi-languages shop countries defined within the same shop, you can pass the shop country ID as countryCode.
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. |
| 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
Return items
When item return is created, the Admin API triggers order-item-returned webhook event.
When a shipment is created, the Admin API triggers order-item-returned webhook event.
SCAYLE allows you to return several items from an order through this method/API. Before initiating a return, ensure the items have been shipped successfully.
Return Processing
To prevent multiple corrective invoices and refund executions for the same order within a short timeframe, SCAYLE opens a 3‑hour internal “return window” when the first return is received, collects any additional return events during that period, and then processes them together via the Return Handler (this window is purely a processing mechanism and not the customer’s return period).
Once SCAYLE processes the return, the following events may occur depending on the feature configuration:
- A refund will be issued for the order.
- A shipment return confirmation email will be sent to the customer.
- An
order-item-returnedwebhook event is triggered when subscribed to.
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. |
| 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. Reason:
|
