Webhook payloads now include a name field in each line_item.merchant object. This field reflects the name in Two Boxes of the merchant the return was created and graded for.

To better support partners, whose LPN formats vary depending on the site receiving the return, we're changing our internal LPN generation to happen only after a site has been assigned to the return line item.

This ensures the LPN format used is the correct one for the site the return line item is graded at. Previously, the LPN was assigned to the return line item when it was created. This meant that the LPN value in webhook payloads was never null, since all webhook events from Two Boxes would trigger after the line item creation point. However going forward, since the LPN won't be assigned until the site is known some events which are triggered prior to this point can have a null LPN.

How this works:

• An LPN is generated only when the return containing the RLI is first scanned. This assignment happens either during the x-ray scan or when the package is scanned for grading using the grading app.
• Before that first scan, we may not yet know the correct site and generating an LPN too early could lead to an invalid format.
• Once an LPN is created, it is permanent and cannot be cleared or regenerated. Impacted events include: return-initiated

For all post-processing webhook events, the lpn field will always have a value, ensuring downstream systems consistently receive the finalized, site-appropriate LPN.

Webhook payloads now include a [3pl] field on each return line item. This field reflects the 3PL where the item was graded.

We've add Site and Merchant objects to the Return Line Item details so that consumers can migrate to using these rather than the merchant integration summary that is being depreciated.

Site

Webhook payloads now include a [site] field on each return line item. This field reflects the actual site where the item was graded. However, please note the following important details about this field:

• For return events that are emitted prior to return processing, the [site] field may be null if we did not receive tracking information at creation time, or it may reflect a best-guess site that could differ from the eventual processing site. Early events that may be impacted include:
  • Return Initiated
  • Return Ignored
  • Return Archived
  • Bulk Return Initiated

For post–return processing events, the [site] field will always be populated and will always reflect the actual site where the return was processed. These events include:

• Return Package Scanned
• Return Line Item Ship Back
• Return Line Item Graded
• Return Complete

Merchant

Webhook payloads now include a [merchant] field on each return line item. This field reflects the Merchant in Two Boxes the return was created for.

The Merchant Integration object will be deprecated and removed from the Return Details payload in 6 months.

This change is related to Two Boxes updating how we internally integrate to the 3rd party providers of merchants. We are decentralizing these integrations so that rather than integrations bundling merchant, site, return provider and product catalog provider, each can be a distinct integration.

Previously, each site that a merchant processed returns at required a distinct merchant integration to couple the merchant to the site. Going forward, merchants will be enabled at multiple sites directly. The result is that we no longer reply on merchant-integrations to determine the merchant and site of a return. Rather, Two Boxes will directly assign the merchant and site to the return itself.

A new "full_name" field has been added to the Customer object in Return Details.

The "full_name" represents the Customer Name captured during for blind returns that are created in Two Boxes using the Work Capture workflow. For returns submitted to Two Boxes through an RMA or custom integration, the customer name will continue to be populated in the "first_name" and "last_name" fields that previously existed in the Customer object.

We’ve released a few updates to the Two Boxes webhooks service that introduces new event types and important payload changes. Please review the details below and update your integrations accordingly.

New Webhook Event Types We’ve added three new events to give you more visibility into return lifecycle changes:

return-archived

• Emitted when a return is archived. Returns can be archived either by the RMA Provider that created them, or by a grader if the return was created as a Work Capture return in Two Boxes.

return-line-item-archived

• Emitted when a line item is removed from a return. This applies only to Work Capture and Bulk Returns created directly by associates in Two Boxes.

return-added

• Emitted when a new line item is added to a return. This can occur when a new item is added to a Work Capture return, when a line is added to a Bulk Return, or when an unexpected item is added to an RMA return.

Payload Updates We’ve updated the webhook payloads with the following changes:

Return Details object

• Added: "return_type": string → Denotes the type of return. Possible values:
  • rma, work-capture, rts, import, unexpected-item, bulk-capture
• Added: "kind": string → Denotes the kind of return. Possible values:
  • production, test
• Removed: "refund_status" → This field has been removed, as it was not being populated (always returned as an empty string).

Return Line Item object

• Added: "quantity": int → Represents the number of units associated with the line item. Relevant to bulk-capture type returns only for now.