Product Guide
Start typing to search…

⚡ Order Workflows

This section describes the lifecycle of an Order when using the Seven Senders API. It focuses on how an order progresses from creation to completion.

Order Lifecycle Overview

flowchart TD

    A["Create Order<br/>POST /order"]
    A --> B["Status: new"]

    B --> C{"Optional<br/>Update Order Status?"}

    C -->|"POST /order-states"| D["Status: paid"]
    D --> E["Status: in_production"]
    E --> F["Status: in_preparation"]

    C -->|"No Update"| G["Wait for Shipment Creation"]
    F --> G

    G --> H["First Shipment Created"]
    H --> I["Status: shipped"]

    I --> J{"Multiple Shipments?"}

    J -->|"Yes"| K["Update Order<br/>PUT /orders/{id}<br/>boarding_complete = true"]
    J -->|"No"| L["Wait for Delivery"]

    K --> L

    L --> M{"All Shipments Delivered?"}

    M -->|"Yes"| N["Status: completed"]
    M -->|"No"| O["Remain in shipped"]

Order API Workflow for Order Creation

Step 1: Authentication

In the first step, you authenticate using the provided API key to request an access token. A detailed explanation is available in the Authentication section.

https://api-uat.sevensenders.com/v2/token
https://api.sevensenders.com/v2/token

Authentication

Authentication is handled via an API key that is assigned to you for the duration of the project. Upon sending the request, the system returns an access token, which remains valid for 60 minutes.

{
  "access_key": "your_apikey"
}
{
  "token": "your_token"
}

Use the returned token in the Authorization header of subsequent requests likePOST Ordersor GET Orders

Authorization: Bearer your_token

Step 2. Create an Order (POST /v2/order)

A full list of all available parameters — including allowed values and whether they are mandatory or optional — can be found in the parameter reference.

https://api-uat.sevensenders.com/v2/order
https://api.sevensenders.com/v2/order
{
  "boarding_complete": true,
  "language": "en",
  "order_date": "2024-01-15T10:30:00Z",
  "order_id": "ORD-2024-001234",
  "order_tags": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "order_url": "https://shop.example.com/orders/ORD-2024-001234",
  "promised_delivery_date": "2024-01-20T23:59:59Z"
}
{
  "boarding_complete": true,
  "language": "en",
  "order_date": "2024-01-15T10:30:00Z",
  "order_id": "ORD-2024-001234",
  "order_tags": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "order_url": "https://shop.example.com/orders/ORD-2024-001234",
  "promised_delivery_date": "2024-01-20T23:59:59Z",
  "state": "new",
  "states_history": [
    {
      "datetime": "2018-08-02T09:24:02.142Z",
      "location": "Berlin",
      "order_id": "12345654",
      "state": "new"
    }
  ],
  "tracking_page_url": "https://tracking.sevensenders.com/order/12345654"
}

When an order is successfully created:

  • The order status is automatically set to new.

Step 2.1. Order Items

Order items represent the individual products contained within an order. Each order can contain one or multiple order items.

Example:

{
    "order_id": "ORD-2024-001234",
    "order_date": "2024-01-15T10:30:00Z",
    "order_url": "https://shop.example.com/orders/ORD-2024-001234",
    "language": "en",
    "promised_delivery_date": "2024-01-20T23:59:59Z",
    "recipient": {
      "first_name": "John",
      "last_name": "Doe",
      "street": "Main Street",
      "house_no": "123",
      "city": "Berlin",
      "zip_code": "10115",
      "country": "DE",
      "email": "[email protected]",
      "phone": "+4930123456"
    },
    "order_items": [
      {
        "description": "Organic Cotton T-Shirt - Blue",
        "external_id": "PROD-12345",
        "hs_code": "6109100010",
        "image_url": "https://shop.example.com/images/tshirt-blue.jpg",
        "item_value": 29.99,
        "origin_country": "PT",
        "quantity": 2,
        "sku": "TSHIRT-BLU-M",
        "weight": 180
      },
      {
        "description": "Canvas Tote Bag - Natural",
        "external_id": "PROD-67890",
        "hs_code": "4202220000",
        "image_url": "https://shop.example.com/images/tote-natural.jpg",
        "item_value": 19.99,
        "origin_country": "IN",
        "quantity": 1,
        "sku": "TOTE-NAT-STD",
        "weight": 250
      }
    ],
    "order_tags": {
      "campaign": "summer_sale",
      "customer_type": "vip"
    }
  }

To create an order item, you can use the following API Call:

https://api-uat.sevensenders.com/v2/orders/{order_id}/items
https://api.sevensenders.com/v2/orders/{order_id}/items
{
  "appearance": "Blue",
  "bundle_item": "BUNDLE-001-ITEM-1",
  "currency": "EUR",
  "description": "Cotton T-Shirt with print",
  "name": "Basic Cotton T-Shirt",
  "returnable": true,
  "sales_price": 29.99,
  "shipment_id": "5678",
  "shop_product_url": "https://shop.example.com/products/basic-tshirt",
  "size": "M",
  "sku": "TSHIRT-BLUE-M",
  "status": "refunded",
  "warehouse": "Main Warehouse Vienna",
  "weight": 0.25
}
{
  "appearance": "Blue",
  "bundle_item": "BUNDLE-001-ITEM-1",
  "currency": "EUR",
  "description": "Cotton T-Shirt with print",
  "id": "987654",
  "name": "Basic Cotton T-Shirt",
  "returnable": true,
  "sales_price": 29.99,
  "shipment_id": "5678",
  "shop_order_id": "ORD-2024-001234",
  "shop_product_url": "https://shop.example.com/products/basic-tshirt",
  "size": "M",
  "sku": "TSHIRT-BLUE-M",
  "status": "new",
  "warehouse": "Main Warehouse Vienna",
  "warehouse_address": "Lagerstraße 5, 1200 Wien, AT",
  "weight": 0.25
}

Step 2.2. Optional Order Status Updates

You may update the order status to reflect your internal fulfillment process.

https://api-uat.sevensenders.com/v2/order_states
https://api.sevensenders.com/v2/order_states

Available Statuses

  • paid — Customer has paid the order.
  • in_production — Items are being produced (e.g. print-on-demand).
  • in_preparation — Order is being picked and packed.

These status updates are optional and can be used to inform customers about order progress.

Step 3. Shipment Creation

When the first shipment for an order is created:

  • The order status automatically changes to shipped.
  • No manual update is required.

Step 4. Boarding Complete (Only for Multiple Shipments)

If an order contains multiple shipments, you must inform Seven Senders once all shipments have been created.

https://api-uat.sevensenders.com/v2/orders/{id}
https://api.sevensenders.com/v2/orders/{id}

{ 
  "boarding_complete": true
}
{
  "boarding_complete": true,
  "language": "en",
  "order_date": "2024-01-15T10:30:00Z",
  "order_id": "ORD-2024-001234",
  "order_tags": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "order_url": "https://shop.example.com/orders/ORD-2024-001234",
  "promised_delivery_date": "2024-01-20T23:59:59Z",
  "state": "new",
  "states_history": [
    {
      "datetime": "2018-08-02T09:24:02.142Z",
      "location": "Berlin",
      "order_id": "12345654",
      "state": "new"
    }
  ],
  "tracking_page_url": "https://tracking.sevensenders.com/order/12345654"
}

This ensures correct order completion handling.

Step 5. Order Completion

An order is marked as completed when:

  • All shipments belonging to the order are delivered.
  • If boarding_complete is used, it must be set to true.

Once these conditions are met, the order automatically transitions to completed.

Step 6. Order Delay (If Promised Delivery Date Is Provided)

If a promised_delivery_date was provided when creating the order:

flowchart TD

    A[Order Created<br/>with promised_delivery_date]
    A --> B{Delivery Later Than Promised?}

    B -->|Yes| C[Order Marked as Delayed]
    B -->|No| D[No Change]

If the current date exceeds the promised delivery date, the order will be marked as delayed.

Order Status Summary

StatusDescription
newOrder created
paidPayment received
in_productionItems being produced
in_preparationOrder being prepared
shippedFirst shipment created
completedAll shipments delivered

Updated 1 day ago

What’s Next