This guide provides a comprehensive reference of all available data fields in the payload for different postback trigger events in GelatoConnect. Understanding these payloads is essential for creating effective templates that extract the information you need.

Introduction

When a postback event is triggered in GelatoConnect, a JSON payload containing event-specific data is sent to your configured endpoint or used in email notifications. This document details the structure and content of these payloads for each event type, helping you understand what data is available when creating your templates.

Package Status Updated
Delayed Order
Order Cancelled
Order Delivered
Order Failed
Order In-Transit
Order Produced
Order Received
Order Returned
Order Shipped

Package Status Updated

This payload is received when a package status changes within the system.

{
  "customer": {
    "id": "ea004496-8a31-42b7-b38a-77791152dbc7",
    "name": "Test Csutomer",
    "referenceId": "test-customer"
  },
  "order": {
    "id": "ceebe91a-42e1-41ae-afdf-64569384f9bc",
    "referenceId": "Test-order",
    "metadata": {
      "isRush": "False"
    }
  },
  "package": {
    "id": "reference_package_id",
    "items": [
      {
        "id": "1614240f-3d24-4d44-b632-b1bd91b1981c",
        "quantity": 1,
        "referenceId": "product_18_reference_id",
        "metadata": {
          "item-type": "product",
          "sku": "product_18_reference_id"
        }
      }
    ],
    "status": "shipped",
    "weight": 9
  },
  "shipment": {
    "fulfillmentLocation": {
      "country": "US",
      "stateProvince": "Wyoming"
    },
    "method": {
      "id": "shipping_method_id",
      "name": "Shipping Method Name"
    },
    "tracking": {
      "code": "tracking_order_us",
      "url": "http://tracking.com/order_us"
    }
  }
}

Key Data Fields

customer: Contains customer information including ID, name, and reference ID
order: Basic order information and any custom metadata
package: Details about the package including its status, weight, and items
shipment: Shipping details including location, method, and tracking information

Delayed Order

This payload is received when orders are identified as delayed beyond their expected dispatch dates.

{
    "currentDate": "2024-11-29 15:55:12",
    "customerId": "9290728b-8534-4227-a191-8036eed9f060",
    "orders": [
        {
            "orderId": "0743ce64d7_test_order_6",
            "orderReferenceId": "G-231211113145",
            "expectedDispatchDate": "2024-09-30"
        },
        {
            "orderId": "0743ce64d7_test_order_128",
            "orderReferenceId": "G-231211113145",
            "expectedDispatchDate": "2024-11-13"
        }
    ]
}

Key Data Fields

currentDate: Current system date and time when the delay was detected
customerId: ID of the customer associated with the delayed orders
orders: Array of delayed orders, each containing:
- orderId: GelatoConnect's internal order ID
- orderReferenceId: Your reference ID for the order
- expectedDispatchDate: The dispatch date that was not met

Order Cancelled

This payload is received when an order is cancelled.

{
  "created": "2018-08-03T07:26:52+00:00",
  "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9",
  "orderReferenceId": "J123X456",
  "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0",
  "fulfillmentStatus": "canceled",
  "channel": "api",
  "comment": "Order canceled successfully",
  "items": [
    {
      "itemReferenceId": "123",
      "fulfillmentStatus": "canceled",
      "metadata": {
        "item-type": "product",
        "sku": "123"
      }
    }
  ],
  "metadata": {
    "isRush": "False"
  }
}

Key Data Fields

created: Timestamp of when the cancellation occurred
orderId: GelatoConnect's internal order ID
orderReferenceId: Your reference ID for the order
customerReferenceId: Reference ID for the customer
fulfillmentStatus: Current status ("canceled")
comment: Information about why or how the order was cancelled
items: Array of items in the order, each with its own status and metadata
metadata: Custom order-level metadata

Order Delivered

This payload is received when an order has been delivered to the recipient.

{
  "created": "2018-08-03T07:26:52+00:00",
  "fulfillmentStatus": "delivered",
  "orderReferenceId": "ASD4124123",
  "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0",
  "channel": "api",
  "comment": "",
  "items": [
    {
      "itemReferenceId": "123",
      "fulfillmentStatus": "delivered",
      "fulfillments": [
        {
          "trackingCode": "code123",
          "trackingUrl": "http://example.com/tracking?code=code123",
          "shipmentMethodName": "DHL Express Domestic BR",
          "shipmentMethodUid": "dhl_express_domestic_br",
          "fulfillmentCountry": "BR",
          "fulfillmentStateProvince": "SP",
          "deliveryDate": "2018-08-05T10:15:00+00:00",
          "recipientName": "John Doe",
          "recipientSignature": "signature_image_url"
        },
        {
          "trackingCode": "code234",
          "trackingUrl": "http://example.com/tracking?code=code234",
          "shipmentMethodName": "DHL Express Domestic BR",
          "shipmentMethodUid": "dhl_express_domestic_br",
          "fulfillmentCountry": "BR",
          "fulfillmentStateProvince": "SP",
          "deliveryDate": "2018-08-05T10:30:00+00:00",
          "recipientName": "Jane Smith",
          "recipientSignature": "signature_image_url_2"
        }
      ],
      "metadata": {
        "item-type": "product",
        "sku": "123"
      }
    }
  ],
  "metadata": {
    "isRush": "False"
  }
}

Key Data Fields

created: Timestamp of when the delivery occurred
fulfillmentStatus: Current status ("delivered")
orderReferenceId: Your reference ID for the order
items: Array of items in the order, each containing:
- fulfillments: Detailed delivery information, including:
  - trackingCode and trackingUrl: Tracking information
  - shipmentMethodName: Carrier name
  - deliveryDate: When the item was delivered
  - recipientName: Who received the package
  - recipientSignature: URL to an image of the signature (if available)

Order Failed

This payload is received when an order fails validation or processing.

{
  "created": "2018-08-03T07:26:52+00:00",
  "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9",
  "orderReferenceId": "J123X456",
  "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0",
  "fulfillmentStatus": "failed",
  "channel": "api",
  "comment": "Order submission failed",
  "items": [
    {
      "itemReferenceId": 123,
      "fulfillmentStatus": "failed",
      "metadata": {
        "item-type": "product",
        "sku": "123"
      }
    }
  ],
  "metadata": {
    "isRush": "False"
  }
}

Key Data Fields

created: Timestamp of when the failure occurred
orderId: GelatoConnect's internal order ID
orderReferenceId: Your reference ID for the order
fulfillmentStatus: Current status ("failed")
comment: Information about why the order failed
items: Array of items in the order, each with its own status and metadata

Order In-Transit

This payload is received when an order is in transit to the recipient.

{
  "created": "2018-09-17T10:26:52+00:00",
  "fulfillmentStatus": "in_transit",
  "orderReferenceId": "J123X456",
  "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0",
  "channel": "api",
  "comment": "Order in-transit",
  "items": [
    {
      "itemReferenceId": "123",
      "fulfillmentStatus": "in_transit",
      "fulfillments": [
        {
          "trackingCode": "code567",
          "trackingUrl": "http://example.com/tracking?code=code567",
          "shipmentMethodName": "DHL Express Domestic BR",
          "shipmentMethodUid": "dhl_express_domestic_br",
          "fulfillmentCountry": "BR",
          "fulfillmentStateProvince": "SP"
        }
      ]
    }
  ]
}

Key Data Fields

created: Timestamp of when the order status changed to in-transit
fulfillmentStatus: Current status ("in_transit")
orderReferenceId: Your reference ID for the order
items: Array of items in the order, each containing:
- fulfillments: Shipping information, including:
  - trackingCode and trackingUrl: Tracking information
  - shipmentMethodName: Carrier name
  - fulfillmentCountry and fulfillmentStateProvince: Origin information

Order Produced

This payload is received when an order has been printed/produced but not yet shipped.

{
  "created": "2018-08-03T07:26:52+00:00",
  "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9",
  "orderReferenceId": "J123X456",
  "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0",
  "fulfillmentStatus": "printed",
  "channel": "api",
  "comment": "Order printed successfully",
  "items": [
    {
      "itemReferenceId": "123",
      "fulfillmentStatus": "printed",
      "metadata": {
        "item-type": "product",
        "sku": "123"
      }
    }
  ],
  "metadata": {
    "isRush": "False"
  }
}

Key Data Fields

created: Timestamp of when the order was produced
orderId: GelatoConnect's internal order ID
orderReferenceId: Your reference ID for the order
fulfillmentStatus: Current status ("printed")
comment: Information about the production
items: Array of items in the order, each with its own status and metadata

Order Received

This payload is received when an order is successfully received and validated in the system.

{
  "created": "2018-08-03T07:26:52+00:00",
  "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9",
  "orderReferenceId": "ASD4124123",
  "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0",
  "fulfillmentStatus": "passed",
  "channel": "api",
  "comment": "Order passed successfully",
  "items": [
    {
      "itemReferenceId": "123",
      "fulfillmentStatus": "passed",
      "metadata": {
        "item-type": "product",
        "sku": "123"
      }
    }
  ],
  "metadata": {
    "isRush": "False"
  }
}

Key Data Fields

created: Timestamp of when the order was received
orderId: GelatoConnect's internal order ID
orderReferenceId: Your reference ID for the order
fulfillmentStatus: Current status ("passed")
comment: Information about the validation
items: Array of items in the order, each with its own status and metadata

Order Returned

This payload is received when an order has been returned to the sender.

{
  "created": "2018-08-03T07:26:52+00:00",
  "fulfillmentStatus": "returned",
  "orderReferenceId": "ASD4124123",
  "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0",
  "channel": "api",
  "comment": "Order returned successfully",
  "items": [
    {
      "itemReferenceId": "123",
      "fulfillmentStatus": "returned",
      "fulfillments": [
        {
          "trackingCode": "code123",
          "trackingUrl": "http://example.com/tracking?code=code123",
          "shipmentMethodName": "DHL Express Domestic BR",
          "shipmentMethodUid": "dhl_express_domestic_br",
          "fulfillmentCountry": "BR",
          "fulfillmentStateProvince": "SP"
        },
        {
          "trackingCode": "code234",
          "trackingUrl": "http://example.com/tracking?code=code234",
          "shipmentMethodName": "DHL Express Domestic BR",
          "shipmentMethodUid": "dhl_express_domestic_br",
          "fulfillmentCountry": "BR",
          "fulfillmentStateProvince": "SP"
        }
      ],
      "metadata": {
        "item-type": "product",
        "sku": "123"
      }
    }
  ],
  "metadata": {
    "isRush": "False"
  }
}

Key Data Fields

created: Timestamp of when the return was processed
fulfillmentStatus: Current status ("returned")
orderReferenceId: Your reference ID for the order
items: Array of items in the order, each containing:
- fulfillments: Return shipment information, including:
  - trackingCode and trackingUrl: Tracking information
  - shipmentMethodName: Carrier name
  - fulfillmentCountry and fulfillmentStateProvince: Origin information

Order Shipped

This payload is received when an order has been shipped to the recipient.

{
  "created": "2018-08-03T07:26:52+00:00",
  "fulfillmentStatus": "shipped",
  "orderReferenceId": "ASD4124123",
  "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0",
  "channel": "api",
  "comment": "Order shipped successfully",
  "items": [
    {
      "itemReferenceId": "123",
      "fulfillmentStatus": "shipped",
      "fulfillments": [
        {
          "trackingCode": "code123",
          "trackingUrl": "http://example.com/tracking?code=code123",
          "shipmentMethodName": "DHL Express Domestic BR",
          "shipmentMethodUid": "dhl_express_domestic_br",
          "fulfillmentCountry": "BR",
          "fulfillmentStateProvince": "SP"
        },
        {
          "trackingCode": "code234",
          "trackingUrl": "http://example.com/tracking?code=code234",
          "shipmentMethodName": "DHL Express Domestic BR",
          "shipmentMethodUid": "dhl_express_domestic_br",
          "fulfillmentCountry": "BR",
          "fulfillmentStateProvince": "SP"
        }
      ],
      "metadata": {
        "item-type": "product",
        "sku": "123"
      }
    }
  ],
  "metadata": {
    "isRush": "False"
  }
}

Key Data Fields

created: Timestamp of when the order was shipped
fulfillmentStatus: Current status ("shipped")
orderReferenceId: Your reference ID for the order
items: Array of items in the order, each containing:
- fulfillments: Shipping information, including:
  - trackingCode and trackingUrl: Tracking information
  - shipmentMethodName: Carrier name
  - fulfillmentCountry and fulfillmentStateProvince: Origin information

Working with Metadata

Many of the event payloads include metadata at both the order and item levels. This metadata contains custom key-value pairs that you can define when submitting orders, which are then included in postback events.

Examples of metadata usage:

Order-level metadata: metadata.isRush with value "False"
Item-level metadata: items[0].metadata.item-type with value "product"
Item-level metadata: items[0].metadata.sku with value "123"

This metadata can be used to include additional information that isn't part of the standard fields, such as priority flags, SKUs, categories, or any other data that helps with your order processing.