HappyColis

Appearance

Webhook Event Payloads ​

Complete reference of webhook event types and their JSON payload formats. Each webhook delivers a message with a header and a body. The header identifies the event, and the body contains the domain-specific payload.

Webhook Message Structure ​

Every webhook message includes a header with the following structure:

json
{
  "id": "WEBHOOK_ID",
  "type": "WEBHOOK_TYPE",
  "timestamp": "WEBHOOK_TIMESTAMP",
  "organization": "ORGANIZATION_ID",
  "application": "APPLICATION_ID"
}

The type field corresponds to one of the event types listed below. The body contains the payload specific to that event type.

Event Types ​

Event TypeDescription
order/createdTriggered when an order has been created
order/updatedTriggered when an order has been updated
order/openedTriggered when an order has been opened
order/completedTriggered when an order has been completed
delivery-order/createdTriggered when a DeliveryOrder has been created
delivery-order/updatedTriggered when a DeliveryOrder has been updated
delivery-order/fulfillment-createdTriggered when a DeliveryOrder fulfillment has been created
delivery-order/completedTriggered when a DeliveryOrder fulfillment has been completed
delivery-order/integratedTriggered when a DeliveryOrder fulfillment has been integrated at warehouse level
delivery-order/integration-errorTriggered when a DeliveryOrder fulfillment has been rejected during the fulfillment process
delivery-order/acceptedTriggered when a DeliveryOrder fulfillment has been accepted
delivery-order/rejectedTriggered when a DeliveryOrder fulfillment has been rejected
delivery-order/pickedTriggered when a DeliveryOrder fulfillment has been picked
delivery-order/packedTriggered when a DeliveryOrder fulfillment has been packed
delivery-order/shippedTriggered when a DeliveryOrder fulfillment has been shipped
shipment/createdTriggered when a Shipment has been created
shipment/deliveredTriggered when a Shipment has been delivered to your customer
shipment/delivered-to-senderTriggered when a Shipment has been delivered to the sender
shipment/returned-to-senderTriggered when a Shipment is being returned to the sender
shipment/in-transitTriggered when a Shipment is in transit
shipment/available-for-pickupTriggered when a Shipment is available at pickup point
shipment/expiredTriggered when a Shipment has expired (lost)
shipment/info-receivedTriggered when a Shipment has been declared to the carrier
shipment/out-for-deliveryTriggered when a Shipment is currently being delivered
shipment/attempt-failedTriggered when a Shipment delivery attempt has failed (customer not available)
product/createdTriggered when a Product has been created
product/updatedTriggered when a Product has been updated
variant/createdTriggered when a Variant has been created
variant/updatedTriggered when a Variant has been updated
variant/deactivatedTriggered when a Variant has been deactivated
variant/activatedTriggered when a Variant has been activated
variant/archivedTriggered when a Variant has been archived
stock-reference/createdTriggered when a StockReference has been created
stock-reference/updatedTriggered when a StockReference has been updated
stock-reference/movementTriggered when a StockReference movement has been registered
stock-reference/archivedTriggered when a StockReference has been archived
stock-reference/acceptedTriggered when a StockReference has been accepted at the warehouse level
stock-reference/rejectedTriggered when a StockReference has been rejected at the warehouse level
stock-reference/snapshotTriggered when a StockReference inventory snapshot was received
transfer-order/createdTriggered when a TransferOrder has been created
transfer-order/openedTriggered when a TransferOrder has been opened
transfer-order/completedTriggered when a TransferOrder has been completed
transfer-order/fulfillment-createdTriggered when a TransferOrder fulfillment has been created
transfer-order/acceptedTriggered when a TransferOrder fulfillment has been accepted
transfer-order/rejectedTriggered when a TransferOrder fulfillment has been rejected
location/createdTriggered when a Location has been created
location/updatedTriggered when a Location has been updated
location/deactivatedTriggered when a Location has been deactivated for fulfillment
location/connectedTriggered when a Location has been connected to a fulfillment service
location/disconnectedTriggered when a Location has been disconnected from a fulfillment service

Payload Examples ​

Order Events ​

Order events contain a complete order object with all its data, including line items, addresses, and pricing information.

json
{
  "id": "ORDER_ID",
  "organization_id": "ORGANIZATION_ID",
  "tpappId": "TPAPP_ID_OPTINAL",
  "reference": "ORDER_REFERENCE",
  "state": "ORDER_STATUS",
  "invoice_number": "YOUR_ORDER_NUMBER_IF_APPLICABLE",
  "issuedAt": "2023-12-08T13:56:00",
  "receivedAt": "2023-12-08T13:56:00",
  "total": 10.0,
  "total_tax_inclusive": 12.0,
  "vat": 0.2,
  "total_tax": 2.0,
  "total_discount": 0.0,
  "total_shipping": 0.0,
  "currency": "EUR",
  "delivery_address": {
    "fullname": "John Doe",
    "address": "1 rue de la paix",
    "address_complement": "Batiment A",
    "city": "Paris",
    "zip_code": "75000",
    "country": "FR",
    "email": "john.doe@change.me",
    "phone": "0123456789"
  },
  "billing_address": {
    "fullname": "John Doe",
    "address": "1 rue de la paix",
    "address_complement": "Batiment A",
    "city": "Paris",
    "zip_code": "75000",
    "country": "FR",
    "email": "john.doe@change.me",
    "phone": "0123456789"
  },
  "lines": [
    {
      "id": "ORDER_LINE_ID",
      "order_line_number": "optional reference to order line number",
      "reference": "YOUR_PRODUCT_SKU",
      "quantity": 2,
      "limit_usage_date": "optional requested use of product with limit usage date",
      "batch_number": "optional requested batch number",
      "unit_price": 10.0,
      "total_price": 20.0,
      "total_price_tax_inclusive": 20.0,
      "vat": 0.2
    }
  ]
}

DeliveryOrder Events ​

DeliveryOrder events contain a complete delivery order object including lines, fulfillments, and event history.

json
{
  "id": "DELIVERY_ORDER_ID",
  "organization_id": "ORGANIZATION_ID",
  "order_number": "DELIVERY_ORDER_REFERENCE",
  "invoice_number": "YOUR_ORDER_NUMBER_IF_APPLICABLE",
  "state": "OPENED",
  "issued_at": "2023-12-08T13:56:00",
  "received_at": "2023-12-08T13:56:00",
  "total": 10.0,
  "total_tax_inclusive": 12.0,
  "vat": 0.2,
  "total_tax": 2.0,
  "total_discount": 0.0,
  "total_shipping": 0.0,
  "currency": "EUR",
  "delivery_address": {
    "fullname": "John Doe",
    "address": "1 rue de la paix",
    "address_complement": "Batiment A",
    "city": "Paris",
    "zip_code": "75000",
    "country": "FR",
    "email": "john.doe@change.me",
    "phone": "0123456789"
  },
  "billing_address": {
    "fullname": "John Doe",
    "address": "1 rue de la paix",
    "address_complement": "Batiment A",
    "city": "Paris",
    "zip_code": "75000",
    "country": "FR",
    "email": "john.doe@change.me",
    "phone": "0123456789"
  },
  "lines": [
    {
      "id": "DELIVERY_ORDER_LINE_ID",
      "order_line_number": "optional reference to order line number",
      "delivery_order_line_number": "DELIVERY_ORDER_LINE_NUMBER",
      "reference": "HAPPY_COLIS_STOCK_REFERENCE",
      "quantity": 2,
      "fulfilled_quantity": 1,
      "fulfillable_quantity": 1,
      "limit_usage_date": "optional requested use of product with limit usage date",
      "batch_number": "optional requested batch number",
      "unit_price": 10.0,
      "total_price": 20.0,
      "total_price_tax_inclusive": 20.0,
      "vat": 0.2
    }
  ],
  "events": [
    {
      "id": "DELIVERY_ORDER_EVENT_ID",
      "type": "OPENED",
      "date": "2023-12-08T13:56:00",
      "message": "Optional message"
    }
  ],
  "fulfillments": [
    {
      "id": "FULFILLMENT_ID",
      "type": "SHIPMENT",
      "reference": "FULFILLMENT_REFERENCE",
      "tracking_number": "TRACKING_NUMBER",
      "carrier": "CARRIER_NAME",
      "tracking_url": "TRACKING_URL",
      "lines": [
        {
          "id": "FULFILLMENT_ID",
          "type": "RECEPTION",
          "reference": "FULFILLMENT_REFERENCE",
          "lines": [
            {
              "id": "FULFILLMENT_LINE_ID",
              "reference": "HAPPY_COLIS_STOCK_REFERENCE",
              "delivery_order_line_number": "DELIVERY_ORDER_LINE_NUMBER",
              "quantity": 2,
              "limit_usage_date": "optional requested use of product with limit usage date",
              "batch_number": "optional requested batch number"
            }
          ]
        }
      ]
    }
  ]
}

Product Events ​

Product events contain a complete product object with all its data and underlying variants. Variants do not include the stock_references property -- listen to variant and stock events for stock data.

json
{
  "id": "PRODUCT_ID",
  "organization_id": "ORGANIZATION_ID",
  "title": "PRODUCT_TITLE",
  "description": "PRODUCT_DESCRIPTION",
  "variants": [
    {
      "id": "VARIANT_ID",
      "sku": "VARIANT_SKU",
      "title": "VARIANT_TITLE",
      "description": "VARIANT_DESCRIPTION",
      "hs_code": "HS_CODE",
      "customs_description": "CUSTOMS_DESCRIPTION",
      "customs_origin": "CUSTOMS_ORIGIN",
      "origin_country": "ORIGIN_COUNTRY",
      "weight": 0.2,
      "weight_unit": "KG",
      "length": 0.2,
      "width": 0.2,
      "height": 0.2,
      "distance_unit": "CM",
      "type": "PRODUCT",
      "images": [
        {
          "id": "IMAGE_ID",
          "url": "IMAGE_URL",
          "title": "IMAGE_TITLE",
          "description": "IMAGE_DESCRIPTION"
        }
      ]
    },
    {
      "id": "VARIANT_ID",
      "sku": "VARIANT_SKU",
      "title": "VARIANT_TITLE",
      "description": "VARIANT_DESCRIPTION",
      "hs_code": "HS_CODE",
      "customs_description": "CUSTOMS_DESCRIPTION",
      "customs_origin": "CUSTOMS_ORIGIN",
      "origin_country": "ORIGIN_COUNTRY",
      "weight": 0.2,
      "weight_unit": "KG",
      "length": 0.2,
      "width": 0.2,
      "height": 0.2,
      "distance_unit": "CM",
      "type": "BUNDLE",
      "links": [
        {
          "variantId": "VARIANT_ID",
          "quantity": 2
        },
        {
          "variantId": "VARIANT_ID",
          "quantity": 1
        }
      ]
    }
  ],
  "images": [
    {
      "id": "IMAGE_ID",
      "url": "IMAGE_URL",
      "title": "IMAGE_TITLE",
      "description": "IMAGE_DESCRIPTION"
    }
  ]
}

Variant Events ​

Variant events contain a complete variant object with all its data, including references and stock references.

json
{
  "id": "VARIANT_ID",
  "organization_id": "ORGANIZATION_ID",
  "sku": "VARIANT_SKU",
  "title": "VARIANT_TITLE",
  "description": "VARIANT_DESCRIPTION",
  "hs_code": "HS_CODE",
  "customs_description": "CUSTOMS_DESCRIPTION",
  "customs_origin": "CUSTOMS_ORIGIN",
  "origin_country": "ORIGIN_COUNTRY",
  "weight": 0.2,
  "weight_unit": "KG",
  "length": 0.2,
  "width": 0.2,
  "height": 0.2,
  "distance_unit": "CM",
  "type": "PRODUCT",
  "images": [
    {
      "id": "IMAGE_ID",
      "url": "IMAGE_URL",
      "title": "IMAGE_TITLE",
      "description": "IMAGE_DESCRIPTION"
    }
  ],
  "references": [
    {
      "reference": "HAPPY_COLIS_STOCK_REFERENCE",
      "type": "SKU"
    },
    {
      "reference": "12345678967890",
      "type": "EAN13"
    }
  ],
  "stock_references": [
    {
      "id": "STOCK_REFERENCE_ID",
      "sku": "STOCK_REFERENCE_SKU",
      "reference": "STOCK_REFERENCE_REFERENCE",
      "critical_threshold": 10,
      "physical_quantity": 10,
      "usable_quantity": 10,
      "reserved_quantity": 0,
      "last_snapshot_at": "2023-12-08T13:56:00",
      "last_snapshot_value": 10,
      "location_id": "LOCATION_ID"
    }
  ]
}

Bundles

Bundles are stored at the location of each component. Ensure you have enough stock at each location where the bundle needs to be prepared. Quantities in stock references for a bundle contain a projected value for each component at the location.

StockReference Events ​

Except for events concerning stock movements, all stock reference events contain a complete stock reference object with all its data and underlying objects.

Entity Payload ​

Used by stock-reference/created, stock-reference/updated, stock-reference/archived, stock-reference/accepted, stock-reference/rejected, and stock-reference/snapshot events.

json
{
  "id": "STOCK_REFERENCE_ID",
  "organization_id": "ORGANIZATION_ID",
  "sku": "STOCK_REFERENCE_SKU",
  "reference": "STOCK_REFERENCE_REFERENCE",
  "critical_threshold": 10,
  "physical_quantity": 10,
  "usable_quantity": 10,
  "reserved_quantity": 0,
  "last_snapshot_at": "2023-12-08T13:56:00",
  "last_snapshot_value": 10,
  "location_id": "LOCATION_ID",
  "product_variant_id": "PRODUCT_VARIANT_ID",
  "model": "PRODUCT",
  "status": "ACTIVE",
  "created_at": "2023-12-08T13:56:00",
  "updated_at": "2023-12-08T13:56:00",
  "units": [
    {
      "quantity": 10,
      "serial_number": "optional requested serial number",
      "limit_usage_date": "optional requested use of product with limit usage date",
      "batch_number": "optional requested batch number",
      "created_at": "2023-12-08T13:56:00"
    }
  ]
}

Movement Payload ​

Used by the stock-reference/movement event. Contains a complete stock movement object along with the related stock reference.

json
{
  "id": "STOCK_REFERENCE_MOVEMENT_ID",
  "type": "INCREMENT",
  "quantity_type": "PHYSICAL",
  "date": "2023-12-08T13:56:00",
  "quantity": 10,
  "executed_quantity": 10,
  "nature": "ORDER",
  "message": "optional message",
  "status": "CONFIRMED",
  "limit_usage_date": "optional requested use of product with limit usage date",
  "batch_number": "optional requested batch number",
  "stock_unit_id": "STOCK_UNIT_ID",
  "stock_reference": {
    "id": "STOCK_REFERENCE_ID",
    "organization_id": "ORGANIZATION_ID",
    "sku": "STOCK_REFERENCE_SKU",
    "reference": "STOCK_REFERENCE_REFERENCE",
    "critical_threshold": 10,
    "physical_quantity": 10,
    "usable_quantity": 10,
    "reserved_quantity": 0,
    "last_snapshot_at": "2023-12-08T13:56:00",
    "last_snapshot_value": 10,
    "location_id": "LOCATION_ID",
    "product_variant_id": "PRODUCT_VARIANT_ID",
    "model": "PRODUCT",
    "status": "ACTIVE",
    "created_at": "2023-12-08T13:56:00",
    "updated_at": "2023-12-08T13:56:00"
  }
}

TransferOrder Events ​

TransferOrder events contain a complete transfer order object with lines, fulfillments, and event history.

json
{
  "id": "DELIVERY_ORDER_ID",
  "organization_id": "ORGANIZATION_ID",
  "supplier_reference": "YOUR_SUPPLIER_ORDER_NUMBER_IF_APPLICABLE",
  "state": "OPENED",
  "issued_at": "2023-12-08T13:56:00",
  "received_at": "2023-12-08T13:56:00",
  "location_id": "location_id",
  "carrier": "CARRIER_NAME",
  "tracking_number": "TRACKING_NUMBER",
  "expected_at": "2023-12-08T13:56:00",
  "shipped_at": "2023-12-08T13:56:00",
  "lines": [
    {
      "id": "TRANSFER_ORDER_LINE_ID",
      "trabsfer_line_number": "DELIVERY_ORDER_LINE_NUMBER",
      "reference": "HAPPY_COLIS_STOCK_REFERENCE",
      "quantity": 2,
      "fulfilled_quantity": 1,
      "fulfillable_quantity": 1,
      "limit_usage_date": "optional requested use of product with limit usage date",
      "batch_number": "optional requested batch number"
    }
  ],
  "events": [
    {
      "id": "TRANSFER_ORDER_EVENT_ID",
      "type": "OPENED",
      "date": "2023-12-08T13:56:00",
      "message": "Optional message"
    }
  ],
  "fulfillments": [
    {
      "id": "FULFILLMENT_ID",
      "type": "RECEPTION",
      "reference": "FULFILLMENT_REFERENCE",
      "lines": [
        {
          "id": "FULFILLMENT_LINE_ID",
          "reference": "HAPPY_COLIS_STOCK_REFERENCE",
          "transfer_line_number": "TRANSFER_ORDER_LINE_NUMBER",
          "quantity": 2,
          "valid_quantity": 2,
          "invalid_quantity": 0,
          "limit_usage_date": "optional requested use of product with limit usage date",
          "batch_number": "optional requested batch number"
        }
      ]
    }
  ]
}

Location Events ​

Location events contain a complete location object with address and configuration data.

json
{
  "id": "LOCATION_ID",
  "name": "LOCATION_NAME",
  "title": "LOCATION_TITLE",
  "description": "LOCATION_DESCRIPTION",
  "active": true,
  "register_all_variants": true,
  "stock_events": true,
  "stock_management": true,
  "type": "WAREHOUSE",
  "address": {
    "fullname": "John Doe",
    "address": "1 rue de la paix",
    "address_complement": "Batiment A",
    "city": "Paris",
    "zip_code": "75000",
    "country": "FR",
    "email": "",
    "phone": ""
  },
  "fulfillment_service_id": "FULFILLMENT_SERVICE_ID_IF_CONNECTED_TO"
}

Shipment Events ​

Shipment events contain a complete shipment object with delivery address, line details, and tracking event history.

json
{
  "id": "SHIPPING_ID",
  "state": "OPENED",
  "reference": "SHIPMENT_INTERNAL_REFERENCE",
  "tracking_number": "TRACKING_NUMBER",
  "shippingMethodName": "SHIPPING_METHOD_NAME",
  "tracking_url": "TRACKING_URL",
  "issued_at": "2023-12-08T13:56:00",
  "received_at": "2023-12-08T13:56:00",
  "delivery_address": {
    "fullname": "John Doe",
    "address": "1 rue de la paix",
    "address_complement": "Batiment A",
    "city": "Paris",
    "zip_code": "75000",
    "country": "FR",
    "email": "",
    "phone": ""
  },
  "details": [
    {
      "id": "SHIPPING_DETAIL_ID",
      "order_line_number": "optional reference to order line number",
      "order_line_id": "optional reference to order line id",
      "delievery_order_line_number": "optional reference to delivery order line number",
      "delievery_order_line_id": "optional reference to delivery order line number",
      "stock_reference_id": "stock_refernce_id",
      "reference": "HAPPY_COLIS_STOCK_REFERENCE",
      "quantity": 2,
      "limit_usage_date": "optional use of product with limit usage date",
      "batch_number": "optional batch number"
    }
  ],
  "events": [
    {
      "id": "SHIPMENT_EVENT_ID",
      "type": "DELIVERED",
      "date": "2023-12-08T13:56:00",
      "message": "Optional message"
    }
  ]
}

HappyColis API Documentation

© 2024 HappyColis. All rights reserved.