Orders

Overview

Order webhooks notify your application when e-commerce orders are created and when their associated payments succeed or fail. Use these events to integrate with fulfillment systems, track payment outcomes, and manage inventory.

Use Cases

Trigger order fulfillment when payment succeeds
Notify customers of failed payments and prompt retry
Sync order data to your ERP or warehouse system
Track inventory changes when orders are placed
Generate shipping labels and packing slips

Events

Event	Description
`order.created`	A new order was placed
`order.payment.succeeded`	Payment for an order succeeded
`order.payment.failed`	Payment for an order failed

order.created

Triggered When

A customer places an e-commerce order via the SDK
An order is created via the Core API

Payload

{
  "type": "order.created",
  "id": "evt_a1B2c3D4e5F6g7H8i9J0k1L2",
  "created": 1704067200,
  "data": {
    "object": {
      "object": "order",
      "id": 100001,
      "address": {
        "object": "address",
        "id": 200001,
        "city": "Springfield",
        "company": null,
        "country": "US",
        "country_name": "United States",
        "created_at": "2026-01-01T12:00:00.000000Z",
        "department": null,
        "first_name": "Jane",
        "is_default": true,
        "last_name": "Doe",
        "line1": "123 Main Street",
        "line2": null,
        "postal_code": "62704",
        "salutation": null,
        "site_ids": [1],
        "state": "IL",
        "state_name": "Illinois",
        "title": null,
        "type": "shipping",
        "updated_at": "2026-01-01T12:00:00.000000Z"
      },
      "amount": 4999,
      "charge": {
        "object": "charge",
        "id": 300001,
        "agency_id": null,
        "amount": 4999,
        "amount_refunded": 0,
        "by_agency": false,
        "created": "2026-01-01T12:00:00.000000Z",
        "created_at": "2026-01-01T12:00:01.000000Z",
        "currency": "usd",
        "customer": {
          "object": "customer",
          "id": 400001
        },
        "description": "Payment for order 100001",
        "disputed": false,
        "failure_code": null,
        "failure_message": null,
        "invoice": {
          "object": "invoice",
          "id": 500001
        },
        "invoice_id": 500001,
        "object_id": "ch_XXXXXXXXXXXXXXXXXXXXXX",
        "offline": false,
        "origin": 1,
        "paid": true,
        "receipt_email": null,
        "receipt_number": null,
        "receipt_url": "https://www.pelcro.com/pdf/receipt/...",
        "reference": null,
        "refunded": false,
        "refunded_at": null,
        "remit_rate": null,
        "remit_rate_amount": null,
        "site_id": 1,
        "source_id": 600001,
        "statement_descriptor": null,
        "status": "succeeded",
        "updated_at": "2026-01-01T12:00:01.000000Z",
        "user_id": 400001
      },
      "coupon": null,
      "created_at": "2026-01-01T12:00:00.000000Z",
      "currency": "usd",
      "customer": {
        "object": "customer",
        "id": 400001,
        "balance": 0,
        "billing_email": null,
        "created": "2025-06-15T10:00:00.000000Z",
        "currency": "usd",
        "default_source": {
          "object": "source",
          "id": 600001,
          "object_id": "pm_XXXXXXXXXXXXXXXXXXXX",
          "object_gateway": "stripe",
          "brand": "visa",
          "country": "US",
          "exp_month": 12,
          "exp_year": 2028,
          "funding": "credit",
          "last4": "4242",
          "site_ids": [1]
        },
        "delinquent": false,
        "display_name": null,
        "email": "[email protected]",
        "email_confirm": 0,
        "email_hardbounce": false,
        "first_name": "Jane",
        "has_password": 1,
        "language": null,
        "last_active_at": 1704067190,
        "last_login_method": "email",
        "last_name": "Doe",
        "mail_marketing": null,
        "metadata": null,
        "object_id": "cus_XXXXXXXXXXXXXX",
        "organization": null,
        "password_last_updated_at": null,
        "phone": null,
        "phone_confirm": null,
        "salutation": null,
        "site_ids": [1],
        "tele_marketing": null,
        "title": null,
        "username": null
      },
      "items": [
        {
          "id": 700001,
          "index": 0,
          "order_id": 100001,
          "product_sku_id": 800001,
          "amount": 4999,
          "quantity": 1,
          "type": "sku",
          "created_at": "2026-01-01T12:00:00.000000Z",
          "updated_at": "2026-01-01T12:00:00.000000Z",
          "deleted_at": null,
          "product_sku": {
            "id": 800001,
            "name": "Premium Widget - Large",
            "product_id": 900001,
            "entitlements": null,
            "metadata": null,
            "countries": null
          }
        }
      ],
      "metadata": null,
      "site_id": 1,
      "status": "paid"
    }
  }
}

order.payment.succeeded

Triggered When

Payment for an order is successfully processed

Payload

The payload structure is identical to order.created. The order status will be "paid" and the nested charge.paid will be true.

{
  "type": "order.payment.succeeded",
  "id": "evt_b2C3d4E5f6G7h8I9j0K1l2M3",
  "created": 1704067210,
  "data": {
    "object": {
      "object": "order",
      "id": 100001,
      "address": { "..." : "same as order.created" },
      "amount": 4999,
      "charge": {
        "object": "charge",
        "id": 300001,
        "amount": 4999,
        "paid": true,
        "status": "succeeded",
        "failure_code": null,
        "failure_message": null,
        "...": "full charge object"
      },
      "coupon": null,
      "created_at": "2026-01-01T12:00:00.000000Z",
      "currency": "usd",
      "customer": { "..." : "full customer object" },
      "items": [ { "..." : "same as order.created" } ],
      "metadata": null,
      "site_id": 1,
      "status": "paid"
    }
  }
}

order.payment.failed

Triggered When

Payment for an order fails (e.g., insufficient funds, card declined)

Payload

The payload structure is identical to order.created, but the order status will be "created" (not yet paid), and the nested charge will contain failure_code and failure_message.

{
  "type": "order.payment.failed",
  "id": "evt_c3D4e5F6g7H8i9J0k1L2m3N4",
  "created": 1704067220,
  "data": {
    "object": {
      "object": "order",
      "id": 100002,
      "address": { "..." : "same as order.created" },
      "amount": 4999,
      "charge": {
        "object": "charge",
        "id": 300002,
        "amount": 4999,
        "paid": false,
        "status": "failed",
        "failure_code": "card_declined",
        "failure_message": "Your card has insufficient funds.",
        "...": "full charge object"
      },
      "coupon": null,
      "created_at": "2026-01-01T12:00:10.000000Z",
      "currency": "usd",
      "customer": { "..." : "full customer object" },
      "items": [ { "..." : "same as order.created" } ],
      "metadata": null,
      "site_id": 1,
      "status": "created"
    }
  }
}

Payload Fields

Order Object

Field	Type	Description
`object`	string	Object type identifier, always `order`
`id`	integer	Unique identifier for the order
`site_id`	integer	Site the order belongs to
`amount`	integer	Order total in cents
`currency`	string	Three-letter ISO currency code
`status`	string	Order status: `"created"`, `"paid"`, `"canceled"`, `"fulfilled"`, `"returned"`
`metadata`	object \| null	Custom key-value metadata
`items`	array	List of order items (see Order Item)
`address`	object \| null	Shipping or billing address (nested Address object)
`customer`	object \| null	Customer who placed the order (nested Customer object)
`charge`	object \| null	First associated charge (nested Charge object with fully expanded `invoice` and `customer`)
`coupon`	object \| null	Applied coupon details
`created_at`	string	ISO 8601 timestamp when the order was created

Order Item Object

Field	Type	Description
`id`	integer	Unique identifier for the order item
`index`	integer	Position of the item in the order (0-based)
`order_id`	integer	Parent order ID
`product_sku_id`	integer	Product SKU ID
`amount`	integer	Item amount in cents
`quantity`	integer	Quantity ordered
`type`	string	Item type (e.g., `"sku"`)
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp
`deleted_at`	string \| null	ISO 8601 timestamp if deleted
`product_sku`	object	Product SKU details (see below)

Product SKU Object (Nested in Order Item)

Field	Type	Description
`id`	integer	SKU ID
`name`	string	SKU display name
`product_id`	integer	Parent product ID
`entitlements`	array \| null	List of entitlement keys granted by this SKU
`metadata`	object \| null	Custom key-value metadata
`countries`	array \| null	Country restrictions

Notes

The charge object is deeply nested and includes a full invoice object (with its own nested customer, source, address_billing, order, and lines). See Invoice Webhooks and Charge Webhooks for detailed field descriptions.
The customer object at the order level and the customer nested inside charge are the same customer — both are fully expanded via CustomerResource.
amount on the order and order items is always in cents (e.g., 4999 = $49.99).
For order.payment.failed, the charge object will contain failure_code (e.g., "card_declined") and failure_message (e.g., "Your card has insufficient funds.").

Webhooks Overview - Setup, signatures, and configuration
Charge Webhooks - Charge object field descriptions
Invoice Webhooks - Invoice object field descriptions

Overview

Use Cases

Events

order.created

Triggered When

Payload

order.payment.succeeded

Triggered When

Payload

order.payment.failed

Triggered When

Payload

Payload Fields

Order Object

Order Item Object

Product SKU Object (Nested in Order Item)

Notes

Related