How to fetch details of shipping paid in Etsy Insider program?

[tedvask]

Hello,

Trying to wrap my head around some Etsy order, and the numbers don't compute for me so far.

Here I have the following flow:

1. Get ledger_entry -- omitted.
2. Get payment from ledger_entry

GET https://openapi.etsy.com/v3/application/shops/REDACTED/payment-account/ledger-entries/payments?ledger_entry_ids=REDACTED&limit=100&offset=0
...

"count": 1,
    "results": [
        {
            "payment_id": REDACTED,
            "buyer_user_id": REDACTED,
            "shop_id": REDACTED,
            "receipt_id": REDACTED,
            "amount_gross": {
                "amount": 2127,
                "divisor": 100,
                "currency_code": "USD"
            },
            "amount_fees": {
                "amount": 89,
                "divisor": 100,
                "currency_code": "USD"
            },
            "amount_net": {
                "amount": 1943,
                "divisor": 100,
                "currency_code": "USD"
            },
            "posted_gross": {
                "amount": 2127,
                "divisor": 100,
                "currency_code": "USD"
            },
            "posted_fees": {
                "amount": 89,
                "divisor": 100,
                "currency_code": "USD"
            },
            "posted_net": {
                "amount": 1943,
                "divisor": 100,
                "currency_code": "USD"
            },
            "adjusted_gross": null,
            "adjusted_fees": null,
            "adjusted_net": null,
            "currency": "USD",
            "shop_currency": "USD",
            "buyer_currency": "USD",
            "shipping_user_id": REDACTED,
            "shipping_address_id": REDACTED,
            "billing_address_id": REDACTED,
            "status": "SETTLED",
            "shipped_timestamp": null,
            "create_timestamp": 1728449566,
            "created_timestamp": 1728449566,
            "update_timestamp": 1728449642,
            "updated_timestamp": 1728449642,
            "payment_adjustments": []
        }
    ]
}

3. Get receipt:

GET https://openapi.etsy.com/v3/application/shops/REDACTED/receipts/REDACTED
. . .
{
    "receipt_id": REDACTED,
    "receipt_type": 0,
    "seller_user_id": REDACTED,
    "seller_email": "REDACTED",
    "buyer_user_id": REDACTED,
    "buyer_email": null,
    "name": "REDACTED",
    "first_line": "REDACTED",
    "second_line": "",
    "city": "REDACTED",
    "state": "REDACTED",
    "zip": "REDACTED",
    "status": "Completed",
    "formatted_address": "REDACTED",
    "country_iso": "US",
    "payment_method": "cc",
    "payment_email": null,
    "message_from_payment": null,
    "message_from_seller": "REDACTED",
    "message_from_buyer": "",
    "is_shipped": true,
    "is_paid": true,
    "create_timestamp": 1728449563,
    "created_timestamp": 1728449563,
    "update_timestamp": 1728484312,
    "updated_timestamp": 1728484312,
    "is_gift": true,
    "gift_message": "",
    "gift_sender": "",
    "grandtotal": {
        "amount": 2127,
        "divisor": 100,
        "currency_code": "USD"
    },
    "subtotal": {
        "amount": 1350,
        "divisor": 100,
        "currency_code": "USD"
    },
    "total_price": {
        "amount": 1350,
        "divisor": 100,
        "currency_code": "USD"
    },
    "total_shipping_cost": {
        "amount": 0,
        "divisor": 100,
        "currency_code": "USD"
    },
    "total_tax_cost": {
        "amount": 95,
        "divisor": 100,
        "currency_code": "USD"
    },
    "total_vat_cost": {
        "amount": 0,
        "divisor": 100,
        "currency_code": "USD"
    },
    "discount_amt": {
        "amount": 0,
        "divisor": 100,
        "currency_code": "USD"
    },
    "gift_wrap_price": {
        "amount": 0,
        "divisor": 100,
        "currency_code": "USD"
    },
    "shipments": [
        {
            "receipt_shipping_id": REDACTED,
            "shipment_notification_timestamp": 1728489600,
            "carrier_name": "USPS",
            "tracking_code": "REDACTED"
        }
    ],
    "transactions": [
        {
            "transaction_id": 4284862003,
            "title": "REDACTED",
            "description": "REDACTED",
            "seller_user_id": REDACTED,
            "buyer_user_id": REDACTED,
            "create_timestamp": 1728449563,
            "created_timestamp": 1728449563,
            "paid_timestamp": 1728449581,
            "shipped_timestamp": 1728484312,
            "quantity": 1,
            "listing_image_id": REDACTED,
            "receipt_id": REDACTED,
            "is_digital": false,
            "file_data": "",
            "listing_id": REDACTED,
            "sku": "REDACTED",
            "product_id": REDACTED,
            "transaction_type": "listing",
            "price": {
                "amount": 700,
                "divisor": 100,
                "currency_code": "USD"
            },
            "shipping_cost": {
                "amount": 0,
                "divisor": 100,
                "currency_code": "USD"
            },
            "variations": [
                {
                    "property_id": REDACTED,
                    "value_id": REDACTED,
                    "formatted_name": "Ribbon length",
                    "formatted_value": "5 Yards"
                }
            ],
            "product_data": [
                {
                    "property_id": REDACTED,
                    "property_name": "Length",
                    "scale_id": 9,
                    "scale_name": "Yards",
                    "value_ids": [
                        REDACTED
                    ],
                    "values": [
                        "5"
                    ]
                }
            ],
            "shipping_profile_id": REDACTED,
            "min_processing_days": 1,
            "max_processing_days": 3,
            "shipping_method": null,
            "shipping_upgrade": null,
            "expected_ship_date": 1728489600,
            "buyer_coupon": 0,
            "shop_coupon": 0
        },
        {
            "transaction_id": REDACTED,
            "title": "REDACTED",
            "description": "REDACTED",
            "seller_user_id": REDACTED,
            "buyer_user_id": REDACTED,
            "create_timestamp": 1728449563,
            "created_timestamp": 1728449563,
            "paid_timestamp": 1728449581,
            "shipped_timestamp": 1728484312,
            "quantity": 1,
            "listing_image_id": REDACTED,
            "receipt_id": REDACTED,
            "is_digital": false,
            "file_data": "",
            "listing_id": REDACTED,
            "sku": "REDACTED",
            "product_id": REDACTED,
            "transaction_type": "listing",
            "price": {
                "amount": 650,
                "divisor": 100,
                "currency_code": "USD"
            },
            "shipping_cost": {
                "amount": 0,
                "divisor": 100,
                "currency_code": "USD"
            },
            "variations": [
                {
                    "property_id": REDACTED,
                    "value_id": REDACTED,
                    "formatted_name": "Ribbon length",
                    "formatted_value": "5 Yards"
                },
                {
                    "property_id": REDACTED,
                    "value_id": REDACTED,
                    "formatted_name": "Primary fabric type",
                    "formatted_value": "Grosgrain"
                }
            ],
            "product_data": [
                {
                    "property_id": REDACTED,
                    "property_name": "Length",
                    "scale_id": 9,
                    "scale_name": "Yards",
                    "value_ids": [
                        REDACTED
                    ],
                    "values": [
                        "5"
                    ]
                },
                {
                    "property_id": REDACTED,
                    "property_name": "Primary fabric type",
                    "scale_id": null,
                    "scale_name": null,
                    "value_ids": [
                        REDACTED
                    ],
                    "values": [
                        "Grosgrain"
                    ]
                }
            ],
            "shipping_profile_id": REDACTED,
            "min_processing_days": 1,
            "max_processing_days": 3,
            "shipping_method": null,
            "shipping_upgrade": null,
            "expected_ship_date": 1728489600,
            "buyer_coupon": 0,
            "shop_coupon": 0
        }
    ],
    "refunds": []
}

So this is how I (try to) make sense of this data:

Product1: $7×1=$7
Product2: $6.5×1=$6.5

• tax $0.95
  = 7+6.5+0.95=14.45

But the grandtotal says $21.27 (!)

21.27-14.45=6.82. What is that?

According to the seller, it is some Free Shipping. Covered by Etsy Insider.

The issue here, how do I make sense of it? How do I understand it? I would expect shipping amounts and shipping adjustments to be populated in the shipping_cost + buyer_coupon maybe?

Perhaps anyone has ideas?

[cyrilchandelier]

Same problem here, Etsy Insider paid for shipping and the money appears in the grandtotal field, but total_shipping_cost is 0 and there is a discrepancy when adding up the other fields (total_price + total_shipping_cost + total_tax_cost + total_vat_cost + gift_wrap_price - discount_amt != grandtotal).

I'm also wondering what to do with these receipts... I'm probably going to flag them as Etsy Insider and move the amount of the discrepancy to total_shipping_cost which is a gross workaround.

[tedvask]

I just wonder if it is safe to assume that the missing_money is always related to Etsy Insider or not. It would be nice if we didn't have to guess but instead received information directly from API :-)

[cyrilchandelier]

Further investigation showed that the missing_money is NOT always related to Etsy Insider... There are a lot of these 0.29 USD charges that represent the Colorado Retail Delivery Fee, and surely there are other things that are not documented.

I ended up creating a new category in my app called "Etsy Adjustments" where I put this missing money... it's lame but better than assuming that it will always be Etsy Insider.

[tedvask]

As for the Colorado Retail Delivery Fee, I found that the 0.29 ones are
coming as separate ledger_entries with type Buyer fee (linked to receipt
by reference_id), e.g.:

{
     "entry_id": REDACTED,
     "ledger_id": REDACTED,
     "sequence_number": REDACTED,
     "amount": -29,
     "currency": "USD",
     "description": "buyer_fee",
     "balance": 87007,
     "create_date": 1728346414,
     "created_timestamp": 1728346414,
     "ledger_type": "buyer_fee",
     "reference_type": "etsy",
     "reference_id": RECEIPT_ID,
     "payment_adjustments": []
},

[cyrilchandelier]

Nice find! But still, I think we all agree the Receipt itself should contain this information, there should be no "missing money".

[AlexeyMeleschenya]

I have the same issue on my side. It will be great if you add some info inside the receipt that contains information about this Buyer fee or something like that