Update order API error

Questions
1

Hi,
I’m updating an order. The only thing I want to do is to add one item to the existing order.

I get two errors that confuse me:

  1. Order version: When I try to update the order and put "version": 1,

it says that the version should be 3 (or sometimes 4) to start.

  1. Question: When I initially send the order (before it gets updated), I’m not assigning a customer ID to it. Is that an issue?

  2. error when updating the order:
    LineItems cannot be modified for finalized tenders.",
    what does it mean or how can I solve it?

My plan was to charge a card on file and then send an update order call when they pressed on adding another item to their order.

{
 "errors": [
   {
     "code": "BAD_REQUEST",
     "detail": "LineItems cannot be modified for finalized tenders.",
     "field": "order.line_items",
     "category": "INVALID_REQUEST_ERROR"
   }
 ]
}

Here’s the request:

curl https://connect.squareup.com/v2/orders/rdT2kmnilMOWqAdvNkZVDmXBrkHZY \
  -X PUT \
  -H 'Square-Version: 2023-04-19' \
  -H 'Authorization: Bearer DELETED' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "86a80e30-e619-4624-8cff-14609352d6d6",
    "order": {
      "version": 3,
      "line_items": [
        {
          "uid": "unique-uid-here-1232",
          "quantity": "1",
          "name": "Name of item HERE",
          "base_price_money": {
            "amount": 100,
            "currency": "EUR"
          }
        }
      ],
      "customer_id": "1F6WQH208N98NNB4YBAGTEB1R8"
    }
  }'
2

At this time line items can’t be added to an order that’s been paid for. Also there are some asynchronous functions/calculations that take place on our end that may bump the order version. When you get this error you can gracefully handle the error by taking the provided order version and retry the request with the provided version. :slightly_smiling_face:

3

So when can I update an order if I can’t update an order after it has been paid for?

Like if I buy something and then I see an upsell after paying, how/can I do this?

Would I have to create the order → not create payment → then update the order → then send payment?

4

At this time order line items can only be updated prior to the order being paid. Updating post payment in an upsell scenario after initial payment isn’t currently available. We’re constantly working to improve our features based on feedback like this, so I’ll be sure to share your request to the API product team. :slightly_smiling_face:

5

Is updating order line items after payment a bad thing? Like, that’s the record of what was bought and paid for, so it’s usually a terrible idea to allow that record to be damaged and could be illegal in some places (as it means one can no longer rely on the order as a single source of Truth, and could be used to support fraud).

However it would be nice if, for example, a notes field or something similar could be updated, as that would allow an issue to be flagged. Or, to have a separate order field called “fulfilment_notes” which might remain writable after the order has been made. Ideally you’d be able to add individual fulfilment notes, including a shipping date etc, or stock problems, and these fields would be permanent; although honestly a simple text field would suffice to start with. There might be far better ways of doing this, have not thought it through at all.