Order events for Stripe Agentic Commerce Suite

Learn how order events are synchronized from commercetools to Stripe after checkout.

After checkout, order status changes in commercetools are synchronized to Stripe as order events.

Stripe surfaces order data to agent experiences, including those powered by Google. These updates ensure buyers see accurate order statuses within the agent interface.

This page describes outbound status synchronization from commercetools to Stripe. For inbound order creation from Stripe to commercetools, see Order import for Stripe Agentic Commerce Suite.

Event and status mapping

Supported state changes from commercetools Messages are mapped to Stripe order event payloads.

Fulfillment events

In the Stripe payload, type is the top-level event category. A value of fulfillment means the event reports fulfillment progress for an Order, and the payload includes a fulfillment object.

The following state changes produce a type: "fulfillment" event:

commercetools trigger message	State or status value	Stripe status
`OrderStateChanged`	`Open`	`pending`
`OrderStateChanged`	`Confirmed`	`confirmed`
`OrderShipmentStateChanged`	`Shipped`	`shipped`
`OrderShipmentStateChanged`	`Delivered`	`delivered`

Adjustment events

In the Stripe payload, type: "adjustment" means the event reports a post-checkout order adjustment, and the payload includes an adjustment object.

The following state changes produce a type: "adjustment" event:

commercetools trigger message	State or status value	Stripe adjustment type
`OrderStateChanged`	`Cancelled`	`cancellation`

If a message type or status is not listed in these tables, the message is ignored and logged as skipped.

Data extraction and fallback logic

A fixed extraction order is applied to build each Stripe event payload.

Order identification

Primary field: custom.fields.stripeOrderId on the commercetools Order.
Fallback: none.

If custom.fields.stripeOrderId is missing or is not a string, processing is aborted for that message.

Line item mapping

Stripe requires line_items for every event. Standard Line Items and Custom Line Items are merged into this array.

Stripe field	Source field	Mapping logic
`line_items[].id`	Standard Line Item	Maps to `variant.sku`.
`line_items[].id`	Custom Line Item	Maps to the Custom Line Item `key`.
`line_items[].quantity`	`quantity`	Uses the Order line item quantity directly.

Tracking information precedence

For confirmed, shipped, and delivered events, tracking data is read from the first Delivery in shippingInfo.deliveries[0].

Stripe field	Precedence and fallback
`carrier`	Uses `parcels[0].trackingData.carrier`. If unavailable, falls back to `delivery.custom.fields.carrier`, then to `""`.
`tracking_number`	Uses `parcels[0].trackingData.trackingId`. If unavailable, falls back to `""`.
`tracking_url`	Uses `delivery.custom.fields.tracking_url`. If unavailable, falls back to `""`.

Timestamps

The following timestamp fields are sent to Stripe in the outbound event payload, generated from commercetools Message data:

occurred_at always uses the commercetools Message createdAt timestamp.
For shipped, shipped_at uses the same Message createdAt timestamp.
For delivered, delivered_at uses the same Message createdAt timestamp.

Technical constraints

Idempotency

The idempotency_key is set to the commercetools Message id. If a message is retried, Stripe receives the same key so duplicate events are not created.

Store scoping

The order.store.key value is validated against the configured ctpStoreKey. If values do not match, the message is ignored to prevent cross-store updates.

Fresh state validation

For each message, a Get Order request is performed before generating the Stripe payload. This ensures the latest Order state is used.

Stripe API request format

Endpoint: POST /v2/delegated_commerce/orders/:stripeOrderId/order_events

Payload shape

Each event contains either a fulfillment object or an adjustment object, depending on the value of the top-level type field. The two objects are never present in the same payload.

A fulfillment event uses the following shape:

Fulfillment event payloadjson
{
  "type": "fulfillment",
  "occurred_at": "2026-06-17T10:30:00.000Z",
  "idempotency_key": "ctp-message-id",
  "fulfillment": {
    "status": "pending | confirmed | shipped | delivered",
    "line_items": [
      {
        "id": "SKU-123",
        "quantity": 1
      }
    ],
    "tracking_number": "1Z999",
    "carrier": "Carrier Name",
    "tracking_url": "https://example.com/track/1Z999",
    "shipped_at": "2026-06-17T10:30:00.000Z",
    "delivered_at": "2026-06-18T16:40:00.000Z"
  }
}

An adjustment event uses the following shape:

Adjustment event payloadjson
{
  "type": "adjustment",
  "occurred_at": "2026-06-17T10:30:00.000Z",
  "idempotency_key": "ctp-message-id",
  "adjustment": {
    "type": "cancellation",
    "status": "completed",
    "description": "Order cancelled",
    "line_items": [
      {
        "id": "SKU-123",
        "quantity": 1
      }
    ]
  }
}

Order events for Stripe Agentic Commerce Suite

Event and status mapping.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Fulfillment events.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Adjustment events.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Data extraction and fallback logic.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Order identification.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Line item mapping.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Tracking information precedence.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Timestamps.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Technical constraints.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Idempotency.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Store scoping.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Fresh state validation.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Stripe API request format.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Payload shape.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}