# Webhooks

Four Fynd Commerce events drive customer synchronization and the post-checkout loyalty lifecycle. Subscribe to the v1 events below. Engage maps each event and emits it to the partner endpoint.

## Required commerce events

| Event | Name and reference | Purpose |
|  --- | --- | --- |
| Order placed | application/order/placed/v1 ↗ | Confirm the redemption hold and identify the cart through `order.cart_info.cart_object_id`. |
| Shipment update | application/shipment/update/v1 ↗ | Credit points on delivery and deduct or refund points for cancellations and returns at shipment level. |
| User create | application/user/create/v1 ↗ | Create the customer in the partner system. |
| User update | application/user/update/v1 ↗ | Synchronize customer profile changes. |


## Read the order-placed payload

Use these fields when processing `application/order/placed/v1`:

| Data | Payload path | Usage |
|  --- | --- | --- |
| Cart reference | `order.cart_info.cart_object_id` | Matches the cart ID used for the redemption hold. |
| Order source | `ordering_source` | `store_os_pos` identifies Store OS orders. `storefront` identifies Fynd-powered storefront orders. |
| Seller item ID | `bags[].article.seller_identifier` | Identifies the seller item in each bag. |
| Redeemed value | `prices.loyalty_discount` | Contains the rewards redemption amount. |
| Value excluding tax | `prices.value_of_good` | Contains the amount excluding tax. |


The `prices` object is available at both order and shipment level.

Shopify order source
The `ordering_source` value for Shopify orders is still to be confirmed. Do not infer this value in production logic

## Shipments, cancellations, and returns

An order can contain multiple shipments. Each shipment has its own delivery, cancellation, and return lifecycle. Process partial and full cancellations or returns at **shipment level**.

Returned items arrive as a separate shipment. Use that shipment's `prices.loyalty_discount` as the amount to refund.

Read `shipment_status.current_shipment_status` and apply the corresponding loyalty action:

| Current shipment status | Meaning | Loyalty action |
|  --- | --- | --- |
| `delivery_done` | Home-delivery shipment delivered | Credit points |
| `handed_over_to_customer` | Order handed over in store | Credit points |
| `refund_completed` | Refund completed for items | Informational |
| `cancelled_customer` | Cancelled by customer | Deduct points |
| `cancelled_fynd` | Cancelled by staff | Deduct points |
| `cancelled_merchant` | Cancelled by seller | Deduct points |
| `refund_initiated` | Refund initiated | Refund points |
| `return_accepted` | Return journey completed | Informational |


Shipment-level accounting
Credit earned points only for terminal delivery statuses. For a cancellation or refund, reverse points against the shipment-level `loyalty_discount`, not the order-level value

## Processing guidance

- Make webhook handling idempotent because events may be retried.
- Resolve the cart before confirming a redemption hold.
- Process each shipment independently.
- Record informational statuses without applying a second loyalty adjustment.
- Keep user-create and user-update processing separate from order and shipment accounting.