Agentic Checkout Webhooks API

Webhook receiver hosted by OpenAI to accept merchant order lifecycle events.

Overview

Below are the data models used in the Checkout Webhooks API.

Endpoints

Receive order lifecycle events

Merchants POST order events so ChatGPT can stay in sync with fulfillment-grade truth. Requests MUST be signed with an HMAC signature in the Merchant-Signature header.

The data field MUST contain the full Order object (not incremental deltas). All optional Order fields (line_items, fulfillments, adjustments, totals) SHOULD be included when available.

requiredenumstring

type

Event type: order_create for new orders, order_update for changes to existing orders

Possible values
`order_create`
`order_update`

requiredEventDataOrder

data

The order object associated with this event

POST /agentic_checkout/webhooks/order_events
{
  "type": "order_create",
  "data": {
    "type": "order",
    "id": "ord_123",
    "checkout_session_id": "checkout_session_123",
    "permalink_url": "https://example.com/orders/123",
    "status": "created",
    "line_items": [
      {
        "id": "li_shoes",
        "title": "Running Shoes",
        "quantity": {
          "ordered": 1,
          "shipped": 0
        },
        "unit_price": 9900,
        "subtotal": 9900
      }
    ],
    "totals": [
      {
        "type": "subtotal",
        "display_text": "Subtotal",
        "amount": 9900
      },
      {
        "type": "fulfillment",
        "display_text": "Shipping",
        "amount": 500
      },
      {
        "type": "tax",
        "display_text": "Tax",
        "amount": 860
      },
      {
        "type": "total",
        "display_text": "Total",
        "amount": 11260
      }
    ]
  }
}

Status Codes:

200 OK - Event accepted
400 Bad Request - Bad payload
401 Unauthorized - Invalid signature
429 - Rate limited
500 Internal Server Error - Server error

Schema objects

Below are the data models used in the Checkout Webhooks API.

Refund

requiredenumstring

type

Method of refund: store_credit for future purchases or original_payment to reverse the charge

Possible values
`store_credit`
`original_payment`

requiredinteger

amount

Refund amount in minor units (e.g. 100 cents for $1.00 or 100 for ¥100)

{
  "type": "original_payment",
  "amount": 1050
}

EventDataOrder

requiredstring

type

Object type discriminator, always 'order'

requiredstring

checkout_session_id

Unique identifier for the checkout session that created this order

requiredstring

permalink_url

Persistent URL where the customer can view order details and status

requiredenumstring

status

Current state of the order in the fulfillment lifecycle

Possible values
`created`
`manual_review`
`confirmed`
`canceled`
`shipped`
`fulfilled`

requiredarrayRefund

refunds

List of all refunds applied to this order

{
  "type": "order",
  "checkout_session_id": "cs_01HV3P3ABC123",
  "permalink_url": "https://merchant.example.com/orders/ord_123456",
  "status": "shipped",
  "refunds": [
    {
      "type": "original_payment",
      "amount": 500
    }
  ]
}

WebhookEvent

requiredenumstring

type

Event type: order_create for new orders, order_update for changes to existing orders

Possible values
`order_create`
`order_update`

requiredEventDataOrder

data

The order object associated with this event

{
  "type": "order_update",
  "data": {
    "type": "order",
    "checkout_session_id": "cs_01HV3P3ABC123",
    "permalink_url": "https://merchant.example.com/orders/ord_123456",
    "status": "shipped",
    "refunds": []
  }
}

Error

requiredenumstring

type

High-level error category

Possible values
`invalid_request`
`processing_error`
`service_unavailable`

requiredstring

code

Specific error code for programmatic handling

requiredstring

message

Human-readable error message

string

param

JSONPath of the offending field if applicable

{
  "type": "invalid_request",
  "code": "missing_required_field",
  "message": "The 'amount' field is required",
  "param": "$.amount"
}