Is this possible? Updating Store/Curb-Pickup Fulfillment via Orders API as we pick each item

Questions
1

We have a problem described in Recommended workaround to sell variable price item... - The Seller Community. Basically we have items we sell in store that are price embedded barcodes (so variable price, but scan at checkout and tracks inventory - lbs of meat).

We use delilabel.app to print these price embedded barcodes. But we can’t sell exactly 0.67lbs of T-Bone stake online, we’d just list 0.75 lb and 1.0 lb. But we need to refund customers if we pick an order under the price they are asking for. And we can’t make refunds a manual process by the store employees, only managers can refund. (Also orders on the online store come in fully paid for, so we can’t edit it before capturing the payment card).

The Idea:

  • We build an app on an iPad that watches for online orders (POST /v2/orders/search - Square API Explorer for recent ones, or order.updated Webhook - Square API Reference)
  • Then also check each of the line items that they can be fulfilled, in the in-app experience you can do this, we’d do the same
  • WHEN THEY ORDER MEAT, we’d prompt for scanning the exact price embedded barcode that it is fulfilled with and issue a refund for the overage square online charged (e.g. purchased 0.75 lb @ 12.99/lb but only picked 0.67lb the difference would be refunded to the card)
  • When one comes in, we have a notification and the person marks it pending via our app (using UpdateOrder and set fulfillment state to PREPARED, and COMPLETED).

EDIT: It looks like that State field is editable by the API API PUT /v2/orders/{order_id} Can't set fulfillment state or order state - #3 by ryanlath, that thread shows how to do so.

Wanted to make sure these order updates are possible. Will be testing too.

2

:wave: 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

Publish your App to the App Marketplace
Square Developer
Square Developer Documentation

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

Yes, your idea is feasible with the Square APIs. You can use the Orders API to watch for online orders and check each of the line items for fulfillment. You can also use the UpdateOrder endpoint to change the fulfillment state to PREPARED and COMPLETED.

For issuing refunds, you can use the Refunds API. When you scan the exact price embedded barcode and calculate the overage, you can create a refund for the difference. This will refund the amount back to the customer’s card.

Remember to handle any errors or edge cases that might occur during this process, such as failed refunds or issues with updating the order status. Also, ensure that your application securely handles sensitive customer information, such as card details, in compliance with PCI standards.

This answer was reviewed by @Bryan-Square.

4

Thanks Bryan, appreciate it.

I think to have inventory correct (a big value of Square, especially when paying for Retail) is we’d need to do two things:

  • do the refund, but the API doesn’t support itemized refunds or exchanges which is actually what we’d want
  • then correct the inventory, possibly by moving the state from SOLD to IN_STOCK. When we look at what the 1st party Retail app does on an exchange is it moves from SOLD to RETURNED_BY_CUSTOMER (but that’s read only InventoryChange Object - Square API Reference) and then to IN_STOCK. I haven’t tried that yet to see if it is possible, or if it correctly tracks inventory.

This is the inventory changes that I see when doing the in 1st party app refund and exchange, but we just can’t set RETURNED_BY_CUSTOMER in the API.

   {
            "type": "ADJUSTMENT",
            "adjustment": {
                "id": "YPJJVDOFLRDYVNAXF46KFY5F",
                "from_state": "SOLD",
                "to_state": "RETURNED_BY_CUSTOMER",
                "location_id": "LTGR8RKS9T3X1",
                "catalog_object_id": "7AT2HW7XAK2S4J445XXRQTFX",
                "catalog_object_type": "ITEM_VARIATION",
                "quantity": "2",
                "total_price_money": {
                    "amount": 300,
                    "currency": "USD"
                },
                "occurred_at": "2024-05-12T13:38:55Z",
                "created_at": "2024-05-12T13:49:55.783Z",
                "transaction_id": "sfL8XP20sLuh91zGdl2JydmeV"
            },
            "measurement_unit": {
                "measurement_unit": {
                    "weight_unit": "IMPERIAL_POUND",
                    "type": "TYPE_WEIGHT"
                },
                "precision": 2
            },
            "measurement_unit_id": "QFHQIDOQC4YL2YFKPB7IHW3G"
        },
        {
            "type": "ADJUSTMENT",
            "adjustment": {
                "id": "LWSXVXQ6255CMWTFYY54L5KB",
                "from_state": "RETURNED_BY_CUSTOMER",
                "to_state": "IN_STOCK",
                "location_id": "LTGR8RKS9T3X1",
                "catalog_object_id": "7AT2HW7XAK2S4J445XXRQTFX",
                "catalog_object_type": "ITEM_VARIATION",
                "quantity": "2",
                "occurred_at": "2024-05-12T13:38:57.396Z",
                "created_at": "2024-05-12T13:38:57.491Z"
            },
            "measurement_unit": {
                "measurement_unit": {
                    "weight_unit": "IMPERIAL_POUND",
                    "type": "TYPE_WEIGHT"
                },
                "precision": 2
            },
            "measurement_unit_id": "QFHQIDOQC4YL2YFKPB7IHW3G"
        }

When restocking it, ideally we could link the transaction_id too of the refund, but that is read only (and deprecated) uggg. The deprecated Transactions API does not have sfL8XP20sLuh91zGdl2JydmeV but calling that on Retrieve Order actually works. Can that field be renamed to order_id? Very confusing, inventory adjustment.transaction_id is really an Order.

5

At this time itemized refunds aren’t currently available with the Refunds API.

Yes, that is confusing that the transaction_id is in the adjustment. I’ve reached out to the team about that. :slightly_smiling_face:

1 Like
6

Thanks, gotcha - sorry I created a separate thread for the docs change about transaction_id so it wouldn’t get missed. Of course you caught it and nothing was missed. Feel free to delete the other thread, no need to clutter. Thanks!