Comprehensive order view via API? (Order, Refunds, Returns, quantities left, etc)

Questions
1

I’m going a little crazy trying to use the API to come back and determine what the actual end result of an order was.

If an purchase was made, and an order created, but there were returns and/or refunds, how do you later find out what the end result of actual quantities of items were still sold to the customer?

I’m pulling up an order using the RetrieveOrder, and in there, under line_item, I see return information, but using the PHP SDK API for an order if I do getReturns() on the order it returns nothing. Looking at the raw JSON from the Retrieve Order, I see it in there, but even then it doesn’t have quantities. If I look up the return order as a separate order and then go through the return line items I could see them, but it isn’t a comprehensive view. And further, how would I even know this existed as the main order via the PHP SDK data doesn’t reflect that anything was returned.

Order zls8ETfFzvdngiJ9HJO1EtUVaaPZY is the one I am looking at as a starting point.

2

Are you starting with the payment? When a payment is refunded we will add the refund_id to the payment. You can then GetRefund which will have the order_id of the refunded order. You will then call RetrieveOrder with the refund order_id to see what was refunded.

If you need to compare the original order with the refunded order the refunded order will have source_order_id which is the original order_id so you can compare. :slightly_smiling_face:

3

This is all very confusing. LoL I’m sure there is a reason, there is always a reason. :wink:

I was starting with an order, but in the way we ultimately are trying to work this, yes, I think it is reasonable we could start with the payment. But this would be the payment for the original order. We need to be able to track from an original payment/order any subsequent refunds/returns that happened so we know what items on the original payment/order may no longer be paid for if you know what I mean.

4

Right, with Square payment orders are all the original order payments. :slightly_smiling_face:

5

I’m not sure I understand that or that it is helpful with getting where I need to go. :slight_smile:

6

What part is still confusing? :slightly_smiling_face:

7

I have no idea how to get all the pieces. If I pull the original payment how do I follow the rabbit trail to know every return and refund that happened on it? I tried using the PHP SDK and the refund and return objects had no data.

8

The payment will contain all the refund_ids that are associated to it. It’s all within the payment response. From there you can get to the orders to get to all the itemized details. :slightly_smiling_face:

9

The data returned via the PHP SDK did not contain any refund or return information which is why I came here to post as I didn’t know how else you would get them. I guess it is a lost cause.

If I do:
GET /v2/orders/zls8ETfFzvdngiJ9HJO1EtUVaaPZY

In the JSON I do see a block in a line item:

"returned_quantities": [
          {
            "uid": "cce8b174-a8a7-4291-b50f-60b60e7d6273",
            "return_order_id": "SDnqjKI0sstON1XTi3qBIx2eV",
            "return_line_item_uid": "cce8b174-a8a7-4291-b50f-60b60e7d6273",
            "refunded_money": {
              "amount": 6360,
              "currency": "USD"
            },
            "state": "COMPLETED",
            "return_line_item_type": "ITEM"
          }
        ],

But I don’t see that anywhere in the data returned by the PHP SDK for the order or line items. Further, that doesn’t have a quantity.

Again, starting with the initial payment or order, it would be nice to have the dots to connect HOW to step from there through all possible returns/refunds to determine the FINAL line items and quantities that were still purchased. Instead of just throwing terms out that don’t help me, a roadmap step by step would be far more useful.

10

With what you have you can take the return_order_id and get this itemized return if it is an itemized return. For the above order its:

{
    "order": {
        "id": "SDnqjKI0sstON1XTi3qBIx2eV",
        "location_id": "5JTA18FX53G3M",
        "created_at": "2024-04-06T13:40:13.000Z",
        "updated_at": "2024-04-06T14:06:03.000Z",
        "state": "COMPLETED",
        "total_tax_money": {
            "amount": 0,
            "currency": "USD"
        },
        "total_discount_money": {
            "amount": 0,
            "currency": "USD"
        },
        "total_tip_money": {
            "amount": 0,
            "currency": "USD"
        },
        "total_money": {
            "amount": 0,
            "currency": "USD"
        },
        "closed_at": "2024-04-06T14:06:03.000Z",
        "total_service_charge_money": {
            "amount": 0,
            "currency": "USD"
        },
        "returns": [
            {
                "source_order_id": "zls8ETfFzvdngiJ9HJO1EtUVaaPZY",
                "return_line_items": [
                    {
                        "uid": "cce8b174-a8a7-4291-b50f-60b60e7d6273",
                        "source_line_item_uid": "4b216b84-bb69-42ce-bac0-095f6338960b",
                        "name": "The Charlotte Mason Elementary Arithmetic Series, Book 5",
                        "quantity": "1",
                        "catalog_object_id": "C5E7SGJFLS5ZWRP7XLDVMWAU",
                        "catalog_version": 1710868042730,
                        "variation_name": "Regular",
                        "item_type": "ITEM",
                        "applied_taxes": [
                            {
                                "uid": "5f28485a-7f85-4cf5-9b4e-0bdf26335159",
                                "tax_uid": "5f28485a-7f85-4cf5-9b4e-0bdf26335159",
                                "applied_money": {
                                    "amount": 460,
                                    "currency": "USD"
                                }
                            }
                        ],
                        "base_price_money": {
                            "amount": 5900,
                            "currency": "USD"
                        },
                        "variation_total_price_money": {
                            "amount": 5900,
                            "currency": "USD"
                        },
                        "gross_return_money": {
                            "amount": 5900,
                            "currency": "USD"
                        },
                        "total_tax_money": {
                            "amount": 460,
                            "currency": "USD"
                        },
                        "total_discount_money": {
                            "amount": 0,
                            "currency": "USD"
                        },
                        "total_money": {
                            "amount": 6360,
                            "currency": "USD"
                        },
                        "total_service_charge_money": {
                            "amount": 0,
                            "currency": "USD"
                        }
                    }
                ],
                "return_taxes": [
                    {
                        "uid": "5f28485a-7f85-4cf5-9b4e-0bdf26335159",
                        "catalog_object_id": "5AJT7TEVPIM6MZNEGXAVDERG",
                        "catalog_version": 1712074131960,
                        "name": "Cincinnati, OH",
                        "type": "ADDITIVE",
                        "percentage": "7.8",
                        "applied_money": {
                            "amount": 460,
                            "currency": "USD"
                        },
                        "scope": "LINE_ITEM"
                    }
                ]
            }
        ],
        "return_amounts": {
            "total_money": {
                "amount": 6360,
                "currency": "USD"
            },
            "tax_money": {
                "amount": 460,
                "currency": "USD"
            },
            "discount_money": {
                "amount": 0,
                "currency": "USD"
            },
            "tip_money": {
                "amount": 0,
                "currency": "USD"
            },
            "service_charge_money": {
                "amount": 0,
                "currency": "USD"
            }
        },
        "net_amounts": {
            "total_money": {
                "amount": -6360,
                "currency": "USD"
            },
            "tax_money": {
                "amount": -460,
                "currency": "USD"
            },
            "discount_money": {
                "amount": 0,
                "currency": "USD"
            },
            "tip_money": {
                "amount": 0,
                "currency": "USD"
            },
            "service_charge_money": {
                "amount": 0,
                "currency": "USD"
            }
        },
        "refunds": [
            {
                "id": "YakFtkIkBd7iSlgO1Lr1nXXjFuuvCBAJJUlyshO85tO",
                "location_id": "5JTA18FX53G3M",
                "transaction_id": "zls8ETfFzvdngiJ9HJO1EtUVaaPZY",
                "tender_id": "H3aI00JtO5aCWUhkyXWjdF9e0gTZY",
                "created_at": "2024-04-06T13:40:13Z",
                "reason": "Returned Goods",
                "amount_money": {
                    "amount": 6360,
                    "currency": "USD"
                },
                "status": "APPROVED"
            }
        ],
        "source": {},
        "net_amount_due_money": {
            "amount": 0,
            "currency": "USD"
        }
    }
}

:slightly_smiling_face:

11

Did you miss the point where I said that data, while in the raw JSON, is not in the data returned via the PHP SDK?