> For the complete documentation index, see [llms.txt](https://docs.partssource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.partssource.com/webhooks-customer/preview/payload-reference.md).

# Payload Reference

Field tables and example deliveries for every webhook event in the upcoming release

{% hint style="warning" %}
**Preview** — this page describes the upcoming release (early September). Content is subject to change until announced in the changelog. Build against the **Current** variant for today's behavior.
{% endhint %}

This page documents the payload of every webhook event in the upcoming release: when it fires, its field table, and a complete example delivery. Events are listed in the [Event Catalog](/webhooks-customer/preview/event-catalog.md).

Each field's **Presence** column states how the field behaves in real deliveries:

| Presence               | Meaning                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Always**             | Present in every delivery                                                                                                                                          |
| **When available**     | Omitted entirely when there is no value — check for key presence rather than a `null` value                                                                        |
| **Not currently sent** | Part of the schema but not populated by this release. Do not build logic against these fields; they will be announced in the changelog before they start appearing |

Note: a small number of **Always** fields may carry a `null` value (e.g. `description`).

Envelope fields (`order_id`, `line_item_id`, `line_item_type`, `company_id`, `occurred_at`) are documented in the [Event Envelope](/webhooks-customer/preview/event-catalog.md#event-envelope) and are generally not repeated inside payload objects.

***

## Order

Full detail for a line item on an order, including pricing, shipping intent, and requester context.

**Used by:** [`customer.order.line.created`](/webhooks-customer/preview/event-catalog.md#customerorderlinecreated)

**Availability:** Production. **Fires when:** A line item was created on an order. Will also begin firing for order lines created through an exchange.

| Field                 | JSON Key                   | Type                         | Presence           | Description                                            |
| --------------------- | -------------------------- | ---------------------------- | ------------------ | ------------------------------------------------------ |
| Description           | `description`              | string                       | Always             | Item description                                       |
| UnitPrice             | `unit_price`               | decimal                      | Always             | Unit price for the line item                           |
| Quantity              | `quantity`                 | int                          | Always             | Quantity ordered                                       |
| UseShippingAccount    | `use_shipping_account`     | bool                         | Always             | Whether the customer's shipping account is used        |
| IsCriticalHardDown    | `is_critical_hard_down`    | bool                         | Always             | Whether this is a critical hard-down request           |
| CustomerPoNumber      | `customer_po_number`       | string                       | When available     | Customer purchase order number                         |
| SourcedPartNumber     | `sourced_part_number`      | string                       | When available     | Part number as sourced by PartsSource                  |
| RequestedPartNumber   | `requested_part_number`    | string                       | When available     | Part number as requested by the customer               |
| Manufacturer          | `manufacturer`             | string                       | When available     | Manufacturer name                                      |
| ManufacturerId        | `manufacturer_id`          | long                         | When available     | Manufacturer identifier                                |
| Condition             | `condition`                | string                       | When available     | Item condition                                         |
| Uom                   | `uom`                      | string                       | When available     | Unit of measure                                        |
| PsListPrice           | `ps_list_price`            | decimal                      | Not currently sent | PartsSource list price                                 |
| Tax                   | `tax`                      | decimal                      | Not currently sent | Tax amount                                             |
| ShipCost              | `ship_cost`                | decimal                      | Not currently sent | Shipping cost                                          |
| Fees                  | `fees`                     | [Fee](#fee)\[]               | When available     | Additional fees (new — populated by this release)      |
| PlannedCarrier        | `planned_carrier`          | string                       | When available     | Intended carrier (new — populated by this release)     |
| PlannedShipMethod     | `planned_ship_method`      | string                       | When available     | Intended ship method (new — populated by this release) |
| EstimatedShipDate     | `estimated_ship_date`      | DateTimeOffset               | When available     | Estimated ship date at time of creation                |
| IfOrderedBy           | `if_ordered_by`            | DateTimeOffset               | Not currently sent | Cutoff time for the quoted ship date                   |
| FacilityId            | `facility_id`              | long                         | When available     | Destination facility identifier                        |
| FacilityName          | `facility_name`            | string                       | When available     | Destination facility name                              |
| ShipAddress           | `ship_address`             | [ShipAddress](#shipaddress)  | When available     | Destination address                                    |
| Requester             | `requester`                | string                       | When available     | Who requested the item                                 |
| RequesterId           | `requester_id`             | long                         | When available     | Requester identifier                                   |
| OrderedBy             | `ordered_by`               | string                       | Not currently sent | Who placed the order — use `ordered_by_id`             |
| OrderedById           | `ordered_by_id`            | long                         | When available     | Orderer identifier                                     |
| IsExchangeRequired    | `is_exchange_required`     | bool                         | When available     | Whether a core exchange is required                    |
| CustomerLineKey       | `customer_line_key`        | string                       | When available     | Customer-supplied line reference                       |
| LineType              | `line_type`                | string                       | When available     | `warranty` or `split`; standard lines omit it (new)    |
| OriginatingLineItemId | `originating_line_item_id` | long                         | When available     | Source line for warranty/split lines (new)             |
| ExceptionReason       | `exception_reason`         | string                       | When available     | `warranty_replacement` on warranty lines (new)         |
| TotalLines            | `total_lines`              | int                          | When available     | Total line count on the order                          |
| LineItemNumber        | `line_item_number`         | int                          | When available     | Position of this line on the order                     |
| Notes                 | `notes`                    | [Notes](#notes)\[]           | When available     | Notes attached to the line                             |
| FieldValues           | `field_values`             | [FieldValue](#fieldvalue)\[] | Not currently sent | Custom field values                                    |

```json
{
  "event_type": "customer.order.line.created",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-15T10:30:00Z",
  "payload": {
    "customer_po_number": "PO-2024-001",
    "requested_part_number": "HYD-3400-PUMP",
    "description": "Hydraulic Pump - 3400 Series",
    "manufacturer": "Acme Parts Co",
    "manufacturer_id": 100,
    "condition": "New",
    "unit_price": 49.99,
    "quantity": 1,
    "fees": [
      { "name": "Hazardous Materials", "value": 15.00 }
    ],
    "planned_carrier": "UPS",
    "planned_ship_method": "Ground",
    "use_shipping_account": false,
    "is_critical_hard_down": false,
    "estimated_ship_date": "2024-01-20T00:00:00Z"
  }
}
```

## OrderLineProcessed

Signals that a line item has met all prerequisites and been released for fulfillment.

**Used by:** [`customer.order.line.processed`](/webhooks-customer/preview/event-catalog.md#customerorderlineprocessed)

**Availability:** Next release. **Fires when:** A line has met all prerequisites and is released for fulfillment. Recommended trigger for downstream fulfillment workflows.

| Field            | JSON Key             | Type     | Presence       | Description                                              |
| ---------------- | -------------------- | -------- | -------------- | -------------------------------------------------------- |
| CustomerPoNumber | `customer_po_number` | string   | Always         | Confirmed PO — present for all order paths at this point |
| ProcessedBy      | `processed_by`       | string   | When available | Absent when processing was fully automated               |
| ProcessedById    | `processed_by_id`    | long     | When available | Absent when automated                                    |
| ProcessedAt      | `processed_at`       | datetime | Always         | When the line was released for fulfillment               |

```json
{
  "event_type": "customer.order.line.processed",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-16T08:00:00Z",
  "payload": {
    "customer_po_number": "PO-2024-001",
    "processed_by": "jsmith@hospital.org",
    "processed_by_id": 4471,
    "processed_at": "2024-01-16T08:00:00Z"
  }
}
```

## OrderLineSplit

Recorded on the original line when it is split into two lines.

**Used by:** [`customer.order.line.split`](/webhooks-customer/preview/event-catalog.md#customerorderlinesplit)

**Availability:** Next release. **Fires when:** A line is split. The new line emits its own `customer.order.line.created` with `line_type: "split"` and `originating_line_item_id` pointing back to this line.

| Field            | JSON Key            | Type     | Presence | Description                     |
| ---------------- | ------------------- | -------- | -------- | ------------------------------- |
| OriginalQuantity | `original_quantity` | int      | Always   | Quantity before the split       |
| UpdatedQuantity  | `updated_quantity`  | int      | Always   | Quantity remaining on this line |
| NewLineItemId    | `new_line_item_id`  | long     | Always   | The newly created line          |
| NewLineQuantity  | `new_line_quantity` | int      | Always   | Quantity moved to the new line  |
| SplitAt          | `split_at`          | datetime | Always   |                                 |

```json
{
  "event_type": "customer.order.line.split",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-16T09:30:00Z",
  "payload": {
    "original_quantity": 5,
    "updated_quantity": 3,
    "new_line_item_id": 67891,
    "new_line_quantity": 2,
    "split_at": "2024-01-16T09:30:00Z"
  }
}
```

## OrderApproval

An approval request awaiting a decision.

**Used by:** [`customer.order.line.approval.requested`](/webhooks-customer/preview/event-catalog.md#customerorderlineapprovalrequested)

**Availability:** Production. **Fires when:** Approval was requested for a line item.

| Field           | JSON Key           | Type           | Presence           | Description                                     |
| --------------- | ------------------ | -------------- | ------------------ | ----------------------------------------------- |
| SubmittedAt     | `submitted_at`     | DateTimeOffset | Always             | When the approval was submitted                 |
| ApprovalLevel   | `approval_level`   | int            | Always             | Remains `1`                                     |
| TotalAmount     | `total_amount`     | decimal        | Always             | Amount requiring approval                       |
| ApprovalId      | `approval_id`      | long           | When available     | Approval identifier                             |
| SubmittedBy     | `submitted_by`     | string         | When available     | Display name of the submitter (all order paths) |
| SubmittedById   | `submitted_by_id`  | long           | When available     | Submitter identifier                            |
| ApprovalType    | `approval_type`    | string         | When available     | Type of approval required                       |
| RejectedAt      | `rejected_at`      | DateTimeOffset | Not currently sent | When rejected, if applicable                    |
| RejectionReason | `rejection_reason` | string         | Not currently sent | Reason for rejection, if applicable             |

```json
{
  "event_type": "customer.order.line.approval.requested",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-15T14:30:00Z",
  "payload": {
    "approval_id": 555,
    "submitted_by": "jsmith@hospital.org",
    "submitted_by_id": 4471,
    "submitted_at": "2024-01-15T14:30:00Z",
    "approval_level": 1,
    "approval_type": "Price Override",
    "total_amount": 1250.00
  }
}
```

## OrderLineApprovalApproved

An approval decision at a single level.

**Used by:** [`customer.order.line.approval.approved`](/webhooks-customer/preview/event-catalog.md#customerorderlineapprovalapproved)

**Availability:** Production. **Fires when:** An intermediate approver approves a line; the final level fires `approval.completed` instead. Fires for intermediate approvals on all order paths.

| Field         | JSON Key         | Type           | Presence       | Description                       |
| ------------- | ---------------- | -------------- | -------------- | --------------------------------- |
| ApprovedById  | `approved_by_id` | long           | Always         | Approver identifier               |
| ApprovedAt    | `approved_at`    | DateTimeOffset | Always         | When approved                     |
| ApprovalLevel | `approval_level` | int            | Always         | Approval level that was satisfied |
| TotalAmount   | `total_amount`   | decimal        | Always         | Amount approved                   |
| ApprovedBy    | `approved_by`    | string         | When available | Who approved                      |

```json
{
  "event_type": "customer.order.line.approval.approved",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-15T16:05:00Z",
  "payload": {
    "approved_by": "mjones@hospital.org",
    "approved_by_id": 8812,
    "approved_at": "2024-01-15T16:05:00Z",
    "approval_level": 1,
    "total_amount": 1250.00
  }
}
```

## OrderLineApprovalCompleted

The terminal approval outcome, once all levels are satisfied.

**Used by:** [`customer.order.line.approval.completed`](/webhooks-customer/preview/event-catalog.md#customerorderlineapprovalcompleted)

**Availability:** Production. **Fires when:** The approval process finished. For punchout orders `customer_po_number` is absent — the ERP generates and transmits the PO after receiving this event.

| Field            | JSON Key             | Type           | Presence       | Description                             |
| ---------------- | -------------------- | -------------- | -------------- | --------------------------------------- |
| ApprovedBy       | `approved_by`        | string         | Always         | Final approver                          |
| ApprovedById     | `approved_by_id`     | long           | Always         | Final approver identifier               |
| ApprovedAt       | `approved_at`        | DateTimeOffset | Always         | When approval completed                 |
| ApprovalLevel    | `approval_level`     | int            | Always         | (new) The final level that was approved |
| TotalAmount      | `total_amount`       | decimal        | Always         | Approved amount                         |
| CustomerPoNumber | `customer_po_number` | string         | When available | Customer purchase order number          |

```json
{
  "event_type": "customer.order.line.approval.completed",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-15T16:30:00Z",
  "payload": {
    "approved_by": "mjones@hospital.org",
    "approved_by_id": 8812,
    "approved_at": "2024-01-15T16:30:00Z",
    "approval_level": 2,
    "total_amount": 1250.00,
    "customer_po_number": "PO-2024-001"
  }
}
```

## OrderLineApprovalRejected

A rejection decision.

**Used by:** [`customer.order.line.approval.rejected`](/webhooks-customer/preview/event-catalog.md#customerorderlineapprovalrejected)

**Availability:** Production. **Fires when:** An approver rejected the line item.

| Field           | JSON Key           | Type           | Presence       | Description                                                          |
| --------------- | ------------------ | -------------- | -------------- | -------------------------------------------------------------------- |
| RejectedBy      | `rejected_by`      | string         | Always         | Who rejected                                                         |
| RejectedById    | `rejected_by_id`   | long           | Always         | Rejecter identifier                                                  |
| RejectedAt      | `rejected_at`      | DateTimeOffset | Always         | When rejected                                                        |
| ApprovalLevel   | `approval_level`   | int            | Always         | Level at which the rejection occurred (corrected on all order paths) |
| TotalAmount     | `total_amount`     | decimal        | Always         | Amount that was rejected                                             |
| RejectionReason | `rejection_reason` | string         | When available | Provided by the approver — continue treating as optional             |

```json
{
  "event_type": "customer.order.line.approval.rejected",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-15T16:20:00Z",
  "payload": {
    "rejected_by": "mjones@hospital.org",
    "rejected_by_id": 8812,
    "rejected_at": "2024-01-15T16:20:00Z",
    "approval_level": 1,
    "rejection_reason": "Exceeds departmental budget for this quarter",
    "total_amount": 1250.00
  }
}
```

## OrderLineBackordered

A backorder notification with reason and expected availability.

**Used by:** [`customer.order.line.backorder.created`](/webhooks-customer/preview/event-catalog.md#customerorderlinebackordercreated)

**Availability:** Production. **Fires when:** A line item was placed on backorder.

| Field           | JSON Key           | Type           | Presence       | Description                   |
| --------------- | ------------------ | -------------- | -------------- | ----------------------------- |
| BackorderedAt   | `backordered_at`   | DateTimeOffset | When available | When the line was backordered |
| BackorderReason | `backorder_reason` | string         | When available | Reason for the backorder      |
| BackorderEta    | `backorder_eta`    | DateTimeOffset | When available | Expected availability date    |

```json
{
  "event_type": "customer.order.line.backorder.created",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-16T09:00:00Z",
  "payload": {
    "backordered_at": "2024-01-16T09:00:00Z",
    "backorder_reason": "Out of stock - expected restock in 2 weeks",
    "backorder_eta": "2024-01-29T00:00:00Z"
  }
}
```

## BackorderUpdated

A revision to an existing backorder, most often a new ETA.

**Used by:** [`customer.order.line.backorder.updated`](/webhooks-customer/preview/event-catalog.md#customerorderlinebackorderupdated)

**Availability:** Production. **Fires when:** Backorder details changed.

| Field                | JSON Key                 | Type           | Presence       | Description                      |
| -------------------- | ------------------------ | -------------- | -------------- | -------------------------------- |
| UpdatedAt            | `updated_at`             | DateTimeOffset | Always         | When the backorder was updated   |
| BackorderEta         | `backorder_eta`          | DateTimeOffset | When available | New expected availability date   |
| PreviousBackorderEta | `previous_backorder_eta` | DateTimeOffset | When available | Prior expected availability date |
| BackorderReason      | `backorder_reason`       | string         | When available | Reason for the change            |

```json
{
  "event_type": "customer.order.line.backorder.updated",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-22T11:15:00Z",
  "payload": {
    "backorder_eta": "2024-02-05T00:00:00Z",
    "previous_backorder_eta": "2024-01-29T00:00:00Z",
    "backorder_reason": "Manufacturer delay",
    "updated_at": "2024-01-22T11:15:00Z"
  }
}
```

## OrderLineCancelled

A terminal cancellation. The line item will not be fulfilled and will not ship.

**Used by:** [`customer.order.line.cancelled`](/webhooks-customer/preview/event-catalog.md#customerorderlinecancelled)

**Availability:** Production. **Fires when:** A line item will not be fulfilled (terminal).

| Field              | JSON Key              | Type           | Presence       | Description                                |
| ------------------ | --------------------- | -------------- | -------------- | ------------------------------------------ |
| LineItemId         | `line_item_id`        | long           | Always         | Cancelled line item identifier             |
| CancellationReason | `cancellation_reason` | string         | Always         | Human-readable cancellation reason         |
| CancellationCode   | `cancellation_code`   | string         | Always         | Machine-readable cancellation code         |
| CancelledAt        | `cancelled_at`        | DateTimeOffset | Always         | When cancelled                             |
| IsRequote          | `is_requote`          | bool           | Always         | `true` when cancelled as part of a requote |
| CancelledBy        | `cancelled_by`        | string         | When available | Who cancelled                              |
| CancelledById      | `cancelled_by_id`     | long           | When available | Canceller identifier                       |

```json
{
  "event_type": "customer.order.line.cancelled",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-16T10:00:00Z",
  "payload": {
    "line_item_id": 67890,
    "cancellation_reason": "Customer Cancelled",
    "cancellation_code": "CUST_CANCEL",
    "cancelled_by": "jsmith@hospital.org",
    "cancelled_by_id": 4471,
    "cancelled_at": "2024-01-16T10:00:00Z",
    "is_requote": false
  }
}
```

{% hint style="info" %}
When `is_requote` is `true`, the line was cancelled as part of a requote rather than abandoned — expect a replacement line item to follow.
{% endhint %}

## Shipment

A shipment with tracking and delivery detail.

**Used by:** [`customer.shipment.shipped`](/webhooks-customer/preview/event-catalog.md#customershipmentshipped)

**Availability:** Production. **Fires when:** A shipment was dispatched.

| Field                 | JSON Key                  | Type           | Presence           | Description                                      |
| --------------------- | ------------------------- | -------------- | ------------------ | ------------------------------------------------ |
| ShipmentType          | `shipment_type`           | string         | Always             | See [Shipment types](#shipment-types)            |
| Direction             | `direction`               | string         | Always             | `to_customer` or `from_customer`                 |
| OccurredAt            | `occurred_at`             | DateTimeOffset | Always             | When the shipment event occurred                 |
| TrackingNumber        | `tracking_number`         | string         | When available     | Primary tracking number                          |
| TrackingNumbers       | `tracking_numbers`        | string\[]      | When available     | All tracking numbers for multi-package shipments |
| Carrier               | `carrier`                 | string         | When available     | Shipping carrier                                 |
| ShipMethod            | `ship_method`             | string         | When available     | Service level                                    |
| ShippedAt             | `shipped_at`              | DateTimeOffset | When available     | When dispatched                                  |
| EstimatedDeliveryDate | `estimated_delivery_date` | DateTime       | When available     | Estimated delivery date                          |
| DeliveredAt           | `delivered_at`            | DateTimeOffset | Not currently sent | When delivered                                   |
| DeliverySignature     | `delivery_signature`      | string         | Not currently sent | Name captured on delivery                        |

```json
{
  "event_type": "customer.shipment.shipped",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-18T15:30:00Z",
  "payload": {
    "shipment_type": "order_fulfillment",
    "direction": "to_customer",
    "occurred_at": "2024-01-18T15:30:00Z",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "ship_method": "Ground",
    "shipped_at": "2024-01-18T15:30:00Z",
    "estimated_delivery_date": "2024-01-20"
  }
}
```

## ShipmentTrackingAssigned

Tracking assignment for a shipment.

**Used by:** [`customer.shipment.tracking.assigned`](/webhooks-customer/preview/event-catalog.md#customershipmenttrackingassigned)

**Availability:** Production. **Fires when:** The shipping label is generated — potentially minutes to days before `customer.shipment.shipped`. Do not treat this event as an indication that the item has shipped.

| Field          | JSON Key          | Type           | Presence | Description                                          |
| -------------- | ----------------- | -------------- | -------- | ---------------------------------------------------- |
| ShipmentType   | `shipment_type`   | string         | Always   | See [Shipment types](#shipment-types)                |
| Direction      | `direction`       | string         | Always   | `to_customer` or `from_customer`                     |
| TrackingNumber | `tracking_number` | string         | Always   | Assigned tracking number                             |
| AssignedAt     | `assigned_at`     | DateTimeOffset | Always   | When tracking was assigned                           |
| Carrier        | `carrier`         | string         | Always   | Shipping carrier — always present as of this release |

```json
{
  "event_type": "customer.shipment.tracking.assigned",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-18T14:00:00Z",
  "payload": {
    "shipment_type": "order_fulfillment",
    "direction": "to_customer",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "assigned_at": "2024-01-18T14:00:00Z"
  }
}
```

## ShipmentTrackingUpdated

Recorded when a tracking number changes after a prior assignment.

**Used by:** [`customer.shipment.tracking.updated`](/webhooks-customer/preview/event-catalog.md#customershipmenttrackingupdated)

**Availability:** Next release. **Fires when:** A tracking number changes after a prior assignment. Fires only in that case, not on every shipment update.

| Field                  | JSON Key                   | Type     | Presence | Description                                |
| ---------------------- | -------------------------- | -------- | -------- | ------------------------------------------ |
| ShipmentType           | `shipment_type`            | string   | Always   | Same values as `customer.shipment.shipped` |
| Direction              | `direction`                | string   | Always   | `to_customer` or `from_customer`           |
| TrackingNumber         | `tracking_number`          | string   | Always   | New tracking number                        |
| Carrier                | `carrier`                  | string   | Always   | New carrier                                |
| PreviousTrackingNumber | `previous_tracking_number` | string   | Always   | Tracking number being replaced             |
| PreviousCarrier        | `previous_carrier`         | string   | Always   |                                            |
| UpdatedAt              | `updated_at`               | datetime | Always   |                                            |

```json
{
  "event_type": "customer.shipment.tracking.updated",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-19T10:00:00Z",
  "payload": {
    "shipment_type": "order_fulfillment",
    "direction": "to_customer",
    "tracking_number": "1Z999AA10123499999",
    "carrier": "FedEx",
    "previous_tracking_number": "1Z999AA10123456784",
    "previous_carrier": "UPS",
    "updated_at": "2024-01-19T10:00:00Z"
  }
}
```

## ShipmentDelivered

Recorded when delivery is confirmed, for outbound fulfillment and customer returns.

**Used by:** [`customer.shipment.delivered`](/webhooks-customer/preview/event-catalog.md#customershipmentdelivered)

**Availability:** Next release. **Fires when:** Delivery is confirmed, for outbound fulfillment and customer returns — automatically from carrier tracking, or by a person confirming receipt.

| Field          | JSON Key          | Type     | Presence       | Description                                                        |
| -------------- | ----------------- | -------- | -------------- | ------------------------------------------------------------------ |
| ShipmentType   | `shipment_type`   | string   | Always         | Same values as `customer.shipment.shipped`                         |
| Direction      | `direction`       | string   | Always         | `to_customer` or `from_customer`                                   |
| TrackingNumber | `tracking_number` | string   | Always         |                                                                    |
| Carrier        | `carrier`         | string   | Always         |                                                                    |
| DeliveredAt    | `delivered_at`    | datetime | Always         |                                                                    |
| UpdatedBy      | `updated_by`      | string   | When available | Present when a person confirmed the delivery — absent if automated |
| UpdatedById    | `updated_by_id`   | long     | When available | Absent if automated                                                |

```json
{
  "event_type": "customer.shipment.delivered",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-20T13:45:00Z",
  "payload": {
    "shipment_type": "order_fulfillment",
    "direction": "to_customer",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "delivered_at": "2024-01-20T13:45:00Z"
  }
}
```

## ShipmentEstimatedShipDateCreated

The first committed ship date for a shipment.

**Used by:** [`customer.shipment.estimated_ship_date.created`](/webhooks-customer/preview/event-catalog.md#customershipmentestimated_ship_datecreated)

**Availability:** Production. **Fires when:** A shipment ship date was committed.

| Field             | JSON Key              | Type           | Presence       | Description                           |
| ----------------- | --------------------- | -------------- | -------------- | ------------------------------------- |
| ShipmentType      | `shipment_type`       | string         | Always         | See [Shipment types](#shipment-types) |
| Direction         | `direction`           | string         | Always         | `to_customer` or `from_customer`      |
| EstimatedShipDate | `estimated_ship_date` | DateTimeOffset | Always         | The committed ship date               |
| CommittedAt       | `committed_at`        | DateTimeOffset | Always         | When the date was committed           |
| ReasonDescription | `reason_description`  | string         | When available | Reason for the date                   |

```json
{
  "event_type": "customer.shipment.estimated_ship_date.created",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-15T14:00:00Z",
  "payload": {
    "shipment_type": "order_fulfillment",
    "direction": "to_customer",
    "estimated_ship_date": "2024-01-18T00:00:00Z",
    "reason_description": "Standard processing time",
    "committed_at": "2024-01-15T14:00:00Z"
  }
}
```

## ShipmentEstimatedShipDateUpdated

A revision to a previously committed shipment ship date.

**Used by:** [`customer.shipment.estimated_ship_date.updated`](/webhooks-customer/preview/event-catalog.md#customershipmentestimated_ship_dateupdated)

**Availability:** Production. **Fires when:** A shipment ship date changed.

| Field                     | JSON Key                       | Type           | Presence       | Description                           |
| ------------------------- | ------------------------------ | -------------- | -------------- | ------------------------------------- |
| ShipmentType              | `shipment_type`                | string         | Always         | See [Shipment types](#shipment-types) |
| Direction                 | `direction`                    | string         | Always         | `to_customer` or `from_customer`      |
| EstimatedShipDate         | `estimated_ship_date`          | DateTimeOffset | Always         | The new ship date                     |
| PreviousEstimatedShipDate | `previous_estimated_ship_date` | DateTimeOffset | Always         | The prior ship date                   |
| UpdatedAt                 | `updated_at`                   | DateTimeOffset | Always         | When the date changed                 |
| ReasonDescription         | `reason_description`           | string         | When available | Reason for the change                 |

```json
{
  "event_type": "customer.shipment.estimated_ship_date.updated",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-17T09:00:00Z",
  "payload": {
    "shipment_type": "order_fulfillment",
    "direction": "to_customer",
    "estimated_ship_date": "2024-01-20T00:00:00Z",
    "previous_estimated_ship_date": "2024-01-18T00:00:00Z",
    "reason_description": "Vendor reported shipping delay",
    "updated_at": "2024-01-17T09:00:00Z"
  }
}
```

## ReturnRequested

A return (RGA) created for a customer return.

**Used by:** [`customer.return.requested`](/webhooks-customer/preview/event-catalog.md#customerreturnrequested)

**Availability:** Next release. **Fires when:** A return (RGA) is created for a customer return.

| Field         | JSON Key          | Type     | Presence       | Description              |
| ------------- | ----------------- | -------- | -------------- | ------------------------ |
| ReturnId      | `return_id`       | long     | Always         | Return (RGA) identifier  |
| Quantity      | `quantity`        | int      | Always         | Quantity being returned  |
| Reason        | `reason`          | string   | When available | Customer-provided reason |
| RequestedBy   | `requested_by`    | string   | Always         |                          |
| RequestedById | `requested_by_id` | long     | Always         |                          |
| RequestedAt   | `requested_at`    | datetime | Always         |                          |

```json
{
  "event_type": "customer.return.requested",
  "company_id": 12345,
  "order_id": 50001,
  "line_item_id": 67890,
  "line_item_type": "part",
  "occurred_at": "2024-01-25T09:15:00Z",
  "payload": {
    "return_id": 8801,
    "quantity": 1,
    "reason": "Wrong part shipped",
    "requested_by": "jsmith@hospital.org",
    "requested_by_id": 4471,
    "requested_at": "2024-01-25T09:15:00Z"
  }
}
```

***

## Shared objects

### Fee

An additional charge. Nested inside [Order](#order). Populated by this release — see the `fees` field.

| Field | JSON Key | Type    | Presence | Description |
| ----- | -------- | ------- | -------- | ----------- |
| Name  | `name`   | string  | Always   | Fee name    |
| Value | `value`  | decimal | Always   | Fee amount  |

### ShipAddress

A destination address. Nested inside [Order](#order).

| Field         | JSON Key          | Type   | Presence       | Description        |
| ------------- | ----------------- | ------ | -------------- | ------------------ |
| ShipAddressId | `ship_address_id` | long   | When available | Address identifier |
| AttentionTo   | `attention_to`    | string | When available | Attention line     |
| EdiSenderCode | `edi_sender_code` | string | When available | EDI sender code    |
| Address1      | `address_1`       | string | When available | Address line 1     |
| Address2      | `address_2`       | string | When available | Address line 2     |
| Address3      | `address_3`       | string | When available | Address line 3     |
| City          | `city`            | string | When available | City               |
| State         | `state`           | string | When available | State or province  |
| ZipCode       | `zip_code`        | string | When available | Postal code        |
| Country       | `country`         | string | When available | Country            |

### Notes

A note attached to a line item. Nested inside [Order](#order).

| Field     | JSON Key      | Type           | Presence           | Description                            |
| --------- | ------------- | -------------- | ------------------ | -------------------------------------- |
| NoteId    | `note_id`     | long           | Always             | Note identifier                        |
| Note      | `note`        | string         | Always             | Note text                              |
| AddedAt   | `added_at`    | DateTimeOffset | Always             | When the note was added                |
| AddedBy   | `added_by`    | string         | Not currently sent | Who added the note — use `added_by_id` |
| AddedById | `added_by_id` | long           | When available     | Author identifier                      |

### FieldValue

A custom field value. Nested inside [Order](#order). The parent `field_values` field is not currently sent.

| Field    | JSON Key    | Type   | Presence       | Description             |
| -------- | ----------- | ------ | -------------- | ----------------------- |
| FieldUid | `field_uid` | string | When available | Field unique identifier |
| Name     | `name`      | string | When available | Field name              |
| Value    | `value`     | string | When available | Field value             |

***

## Enumerations

### Shipment types

Used by the `shipment_type` field on all shipment payload objects.

| Value                  | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `order_fulfillment`    | Standard outbound fulfillment                     |
| `depot_repair_return`  | Item returning to the customer after depot repair |
| `depot_repair_intake`  | Item being sent in for depot repair               |
| `exchange_core_return` | Core being returned under an exchange             |
| `customer_return`      | Customer-initiated return                         |
| `loaner_outbound`      | Loaner unit sent to the customer                  |

### Line item types

Used by the `line_item_type` envelope field.

| Value             | Description                 |
| ----------------- | --------------------------- |
| `part`            | Physical part               |
| `depot_flat_rate` | Depot repair at a flat rate |
| `depot_quoted`    | Depot repair, quoted        |
| `service`         | On-site or remote service   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.partssource.com/webhooks-customer/preview/payload-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.