Skip to content

Status Postback

The status postbacks are json messages back to GelatoConnect API to keep us and our customers updated on the production status of the order. Following statuses can be posted back to Gelato:

  • received - postback expected immediately after order received, to confirm successful processing in your system. This status is mandatory
  • error - postback expected in case of any error, either submission error (when status "received" can not be provided)
  • printed - postback expected when an order item or the entire order has been finished printed. This status is optional
  • shipped – postback expected when an order item or the entire order has been shipped. This status is mandatory
  • cancelled - postback expected when an order item or the entire order has been cancelled in your system. This status is mandatory

Post backs can be submitted either for an entire order or for each individual order item. If you are sending for each individual order item, we expect you to send back post backs for each order item in the order, for our system to mark it as completed

POST /v2/order/status

Request example

{
  "timestamp": "2008-09-15T15:53:00Z",
  "orderId": "d290f1ee",
  "status": "received",
  "message": "The order has been shipped",
  "trackingCode": "RT1235D",
  "trackingLink": "https://test.com"
}

Success response example

{
  "message": "order status update has been sent"
}

Error response example

{
  "error": "invalid request"
}

Partial Cancellation

For cancelled status, you can specify individual order items to cancel partially or fully. This is useful when only some items in an order need to be cancelled, or when only a portion of an item's quantity should be cancelled.

Partial Cancellation Request Format

Parameter Type Description
items array Optional. List of order items to cancel. If not provided, all items in the order are cancelled.
items[].orderItemId string Required. The order item ID to cancel (must be a valid integer as string).
items[].quantity int Optional. The quantity cancelled. If not provided, the entire item is cancelled.

Partial Cancellation Examples

Example 1: Cancel specific items without quantity (entire items cancelled)

{
  "timestamp": "2008-09-15T15:53:00Z",
  "orderId": "d290f1ee",
  "status": "cancelled",
  "message": "Partial cancellation due to stock issue",
  "items": [{ "orderItemId": "12345" }, { "orderItemId": "12346" }]
}

Example 2: Cancel specific items with quantity (partial quantity cancelled)

{
  "timestamp": "2008-09-15T15:53:00Z",
  "orderId": "d290f1ee",
  "status": "cancelled",
  "message": "Partial cancellation - 5 units cancelled from item 12345",
  "items": [
    { "orderItemId": "12345", "quantity": 5 },
    { "orderItemId": "12346" }
  ]
}

Example 3: Full order cancellation (no items array)

{
  "timestamp": "2008-09-15T15:53:00Z",
  "orderId": "d290f1ee",
  "status": "cancelled",
  "message": "Full order cancellation"
}

Partial Cancellation Behavior

  • If items array is provided:

  • Only the specified order items will be moved to manual_handling status

  • If quantity is provided, the status log will include the cancelled quantity
  • If quantity is not provided, the entire item is considered cancelled

  • Items not listed in the array will remain unchanged

  • If items array is not provided:

  • All items in the order will be moved to manual_handling status

  • Items that are already in shipped or cancelled status will not be affected

Note: The items array is only valid for cancelled status. Providing it with any other status will result in a validation error.

Request

Parameter Type Description
timestamp (required) string Date the status is sent by the partner system to GelatoConnect API, in ISO*8601.
_Sample: 2008-09-15T15:53:00Z._
orderId (required) string Gelato submitted ID.
Sample: d290f1ee.
status (required) string One of the supported values (see below):
• received - postback expected immediately after order received
• error - postback expected in case of any error
• printed - postback expected when print job printed
• shipped - postback expected when order shipped
• cancelled - postback expected when order cancelled on the partner side.
Sample: received.
message string Mandatory for status error, but can be provided with any other status. Sample: The order has been shipped.
trackingCode string Optional information to be provided with status shipped when not using Gelato dispatchOrder.
Sample: RT1235D.
trackingLink string Optional information to be provided with status shipped when not using Gelato dispatchOrder.
Sample: https://test.com.
items array Optional. Only allowed for cancelled status. List of order items for partial cancellation. If not provided, all items in the order are cancelled. See Partial Cancellation section below.

Success response

Parameter Type Description
message (required) string The message with the success.
Sample: subscribed webhook.

Error response

Parameter Type Description
error (required) string The message with the error.
Sample: invalid request.