Orders

Orders are the key data objects to understand when working with Skrym. The following points are important to keep in mind regarding our definition of an order:

• Every order should have a unique identifier
• An order should contain at least one item
• An order constitutes a promise to deliver goods
• An order can be split into multiple order parts (e.g., for partial delivery)
• An order is delivered through one or more Shipments, each of which can have multiple tracked parcels

Creating and updating orders

Use the UpsertOrders endpoint to create or update orders in Skrym:

This endpoint allows you to register orders with their items, references, and optional shipping information.

Here's a minimal example of upserting an order:

{
  "orders": [
    {
      "referencesWithType": [
        {
          "reference": "ORDER-1",
          "referenceType": "EXTERNAL"
        }
      ],
      "originCountry": "SE",
      "originZip": "11428",
      "destinationZip": "12345",
      "destinationCountry": "SE",
      "orderDate": "2026-01-15T10:00:00Z",
      "products": [
        {
          "quantity": 2,
          "externalId": "PROD-ABC-123"
        }
      ]
    }
  ]
}

Specifying transporters and methods

If you want to specify a transporter and method for an order, you'll need to provide the internal Skrym IDs for these entities. To obtain these IDs and their corresponding aliases (which can help with matching):

1. Use the GetMethodsForRetailer endpoint to retrieve available transporters and methods:

2. This endpoint returns the Skrym IDs along with aliases that you can use to facilitate matching between your system and Skrym's transporters and methods.

Order references

Order references are identifiers that link orders across different systems. Each order can have multiple references, allowing it to be tracked and identified through various stages of the fulfillment process.

Reference types

Each order reference has a type that indicates its origin and purpose:

• SHIPMENT - Reference from shipment tracking systems
• PARCEL - Reference from parcel tracking systems
• EXTERNAL - External reference from third-party systems
• SKRYM - Skrym internal reference
• INVOICE_CONTROL - Reference from invoice control systems
• CHECKOUT - Reference from the checkout process

Note: Shipment and parcel tracking references should not usually be added as order references when creating or updating orders. These are typically added automatically by Skrym when shipments and parcels are created through the booking process.

When creating or updating orders, if no reference type is specified, it will be empty. Reference types help identify the source and purpose of each reference, making it easier to trace orders through different systems and processes.

Organization ID in references

The createdByOrganizationId field in references is used to track which system a specific reference belongs to. By default, it is set to the authenticated organization.

If you need to use a specific UUID for your e-commerce platform, ERP, WMS, or other systems, please contact Skrym support who will provide you with the appropriate organization ID value to use.

For example, if you integrate with multiple systems, you can differentiate between them using organization IDs:

This allows you to maintain multiple references for the same order from different systems, making it easy to trace orders across your entire logistics chain.

Order parts

An order part is a partition of an order and must have at least one item. If an order part is split, it removes the previous part and creates two new parts.

Order parts are intended to register information after an order has been processed - for example, when an order is split during delivery in the warehouse, or when partial shipments are created.

Creating and updating order parts

Use the UpsertOrderParts endpoint to split orders into multiple parts or associate products with specific shipment references:

This is useful when you need to:

• Split an order into multiple shipments for partial delivery
• Create separate parts for different shipping methods or carriers
• Track which products are in which shipment
• Handle returns as separate order parts
• Associate products with specific tracking numbers or parcel references

You can identify orders using either the Skrym order ID or your own external order reference. Similarly, products can be identified using Skrym product IDs or your external product IDs. If a product doesn't exist yet, you can provide product details and it will be created automatically.

Each order part can include optional information such as origin and destination locations, shipment references, parcel references, transporter details, and pricing information for each product.