--- updatedAt: 2026-02-24T16:50:47.000Z agentTools: projectIndex: https://docs.pelcro.com/llms.txt --- # Orders Receive notifications when e-commerce orders are created and when payments succeed or fail. ## 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`](#ordercreated) | A new order was placed | | [`order.payment.succeeded`](#orderpayment_succeeded) | Payment for an order succeeded | | [`order.payment.failed`](#orderpayment_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 ```json { "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": "customer@example.com", "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`. ```json { "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`. ```json { "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](#order-item-object)) | | `address` | object \| null | Shipping or billing address (nested [Address](https://docs.pelcro.com/docs/webhooks-addresses) object) | | `customer` | object \| null | Customer who placed the order (nested [Customer](https://docs.pelcro.com/docs/webhooks-customers) object) | | `charge` | object \| null | First associated charge (nested [Charge](https://docs.pelcro.com/docs/webhooks-charges) 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](https://docs.pelcro.com/docs/webhooks-invoices) and [Charge Webhooks](https://docs.pelcro.com/docs/webhooks-charges) 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."`). *** ## Related * [Webhooks Overview](webhooks) - Setup, signatures, and configuration * [Charge Webhooks](https://docs.pelcro.com/docs/webhooks-charges) - Charge object field descriptions * [Invoice Webhooks](https://docs.pelcro.com/docs/webhooks-invoices) - Invoice object field descriptions # Sibling pages * [Email Templates](https://docs.pelcro.com/docs/e-mail-templates-for-webhooks.md) * [Addresses](https://docs.pelcro.com/docs/webhooks-addresses.md) * [Bills](https://docs.pelcro.com/docs/webhooks-bills.md) * [Campaigns](https://docs.pelcro.com/docs/webhooks-campaigns.md) * [Charges](https://docs.pelcro.com/docs/webhooks-charges.md) * [Customers](https://docs.pelcro.com/docs/webhooks-customers.md) * [Exports](https://docs.pelcro.com/docs/webhooks-exports.md) * [Fraud Prevention](https://docs.pelcro.com/docs/webhooks-fraud-prevention.md) * [Invoices](https://docs.pelcro.com/docs/webhooks-invoices.md) * [Members](https://docs.pelcro.com/docs/webhooks-members.md) * [Newsletters](https://docs.pelcro.com/docs/webhooks-newsletters.md) * [Payment Methods](https://docs.pelcro.com/docs/webhooks-payment-methods.md) * [Plans](https://docs.pelcro.com/docs/webhooks-plans.md) * [Products](https://docs.pelcro.com/docs/webhooks-products.md) * [Subscriptions](https://docs.pelcro.com/docs/webhooks-subscriptions.md) * [Vendors](https://docs.pelcro.com/docs/webhooks-vendors.md)