Line Items for Orders Not Guaranteed After a Payment is Completed?

Questions
1

Hey folks,

I’m integrating with Square’s Payments and Orders APIs, and I’ve run into some confusing behavior that I’d like clarification on.

Scenario:

  • I listen to payment.created / payment.updated webhooks.

  • When I receive a payment event, I use the payment.order_id to call RetrieveOrder.

  • I successfully get back the order and store the id for future processing.

  • Then, since my workflow depends on checking line_items for a specific product to trigger downstream logic, I query again to get line items.

Issue:
Sometimes, immediately after a payment.created or payment.updated event, calling RetrieveOrder returns an order object with no line items. If I retry the exact same RetrieveOrder call later (manually or after a short delay), the line_items array is present and contains the expected items.

Questions:

  1. Is this expected behavior — i.e., that line_items might not be populated immediately when an order is first created/linked to a payment?

  2. Does Square guarantee any ordering between payment.* webhooks and line items being attached to an order?

  3. If this is expected, is the advice the typical flow of backoff retries and such?

My main concern is making sure I follow Square’s recommended approach rather than working around something incorrectly.

Thank you for your help in clarifying whether this is an architectural expectation, or something else. Thanks!

2

:waving_hand: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Orders API
Retrieve Orders
Retrieve Payments

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

  1. Is this expected behavior — i.e., that line_items might not be populated immediately when an order is first created/linked to a payment?

    Yes, this behavior can occur. When a payment is created or updated, there might be a slight delay before all associated data, such as line_items, is fully populated in the order object. This is because the order and payment processes can be asynchronous, and the data might not be immediately available at the time the webhook event is triggered.

  2. Does Square guarantee any ordering between payment.* webhooks and line items being attached to an order?

    Square does not guarantee a specific order in which payment.* webhooks and the population of line_items in an order occur. The webhook event for a payment might be received before the order is fully updated with all its details, including line_items.

  3. If this is expected, is the advice the typical flow of backoff retries and such?

    Yes, implementing a retry mechanism with backoff is a recommended approach. If you encounter an order object without line_items, you can wait for a short period and then retry the RetrieveOrder call. This allows time for the order data to be fully populated. Additionally, ensure that your application can handle such scenarios gracefully by implementing retries with exponential backoff to avoid overwhelming the system with requests.

This answer was reviewed by @Bryan-Square.