What's new?
We added two new objects to transaction.details to make it easier to work with adjustments.
details object
Calculated totals for a transaction, including proration, discounts, tax, and currency conversion. Considered the source of truth for totals on a transaction.
adjusted_totals object or null
Transaction totals adjusted to reflect any refunds or chargebacks. null if no adjustments against this transaction.
adjusted_payout_totals object or null
Payout totals adjusted to reflect any refunds or chargebacks. null if no adjustments against this transaction.
These objects complement the existing transaction.details.totals and transaction.details.payout_totals objects. They show how the transaction totals and payout totals are impacted by any adjustments.
How it works
Paddle returns details.totals and details.payout_totals for transactions. However, these objects aren't impacted by adjustments.
This made it difficult to see how much a transaction is for and what you earned. You'd need to use the include parameter to return adjustments, then sum transaction.adjustments[].totals.total, then deduct this from the transaction totals.
The new objects return adjusted totals without the need to include adjustments or do any of your own calculations.
Examples
GET
/transactions/{transaction_id} { "data": { "id": "txn_01h3h8qvbbgsvvakck3w432t7p", "status": "completed", "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a", "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5", "business_id": null, "custom_data": null, "origin": "subscription_recurring", "collection_mode": "automatic", "subscription_id": "sub_01h3h3a9sfpr5syq38tq0sd4sp", "invoice_id": "inv_01h3h8r15a22r1pjyv834d0dat", "invoice_number": "325-10051", "billing_details": null, "billing_period": { "starts_at": "2023-08-22T08:25:12.565118Z", "ends_at": "2023-09-22T08:25:12.565118Z" }, "currency_code": "USD", "discount_id": null, "created_at": "2023-06-22T10:00:01.785157Z", "updated_at": "2023-06-22T10:00:09.653782Z", "billed_at": "2023-06-22T10:00:01.131262Z", "items": [ { "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "description": "Monthly (per seat)", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "billing_cycle": { "interval": "month", "frequency": 1 }, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "3000", "currency_code": "USD" }, "unit_price_overrides": [], "quantity": { "minimum": 10, "maximum": 999 }, "status": "active" }, "quantity": 10 }, { "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "description": "Monthly (recurring addon)", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "billing_cycle": { "interval": "month", "frequency": 1 }, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "10000", "currency_code": "USD" }, "unit_price_overrides": [], "quantity": { "minimum": 1, "maximum": 100 }, "status": "active" }, "quantity": 1 } ], "details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "40000", "discount": "0", "tax": "3549", "total": "43549" } } ], "totals": { "subtotal": "40000", "tax": "3549", "discount": "0", "total": "43549", "grand_total": "12567", "fee": "2227", "credit": "30982", "balance": "0", "earnings": "37773", "currency_code": "USD" }, "adjusted_totals": { "subtotal": "10005", "tax": "887", "total": "10892", "grand_total": "10892", "fee": "557", "earnings": "9448", "currency_code": "USD" }, "payout_totals": { "subtotal": "40000", "tax": "3549", "total": "43549", "fee": "2227", "earnings": "37773", "currency_code": "USD" }, "adjusted_payout_totals": { "subtotal": "10005", "tax": "887", "total": "10892", "fee": "557", "chargeback_fee": { "amount": "0", "original": null }, "earnings": "9448", "currency_code": "USD" }, "line_items": [ { "id": "txnitm_01h3h8qvs7cmyyb9fs92hqbzdh", "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 10, "totals": { "subtotal": "30000", "tax": "2662", "discount": "0", "total": "32662" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "tax": "266", "discount": "0", "total": "3266" } }, { "id": "txnitm_01h3h8qvs7cmyyb9fs95jkr9sk", "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" } } ] }, "payments": [ { "payment_attempt_id": "6d81dac9-1074-48e5-bc60-5c0ff50dfe1c", "stored_payment_method_id": "badbd3d8-df98-4aa4-b7ba-5e9ad85b4488", "amount": "12567", "status": "captured", "error_code": null, "method_details": { "type": "card", "card": { "type": "visa", "last4": "4242", "expiry_month": 1, "expiry_year": 2026 } }, "created_at": "2023-06-22T10:00:02.58261Z", "captured_at": "2023-06-22T10:00:05.387088Z" } ], "checkout": { "url": "https://aeroedit.com/pay?_ptxn=txn_01h3h8qvbbgsvvakck3w432t7p" } }, "meta": { "request_id": "4dc83732-b11c-44c7-88fa-f76de266d53e" }}Next steps
This change is available in version 1 of the Paddle API.
It's a non-breaking change, meaning it doesn't impact existing integrations.
You can list transactions or get a transaction using the API to see the new objects.
Summary of changes
| Entity | Field | Change | Type |
|---|---|---|---|
| Transaction | adjusted_totals | + Added | Field |
| Totals after adjustments, under transaction.details. | |||
| Transaction | adjusted_payout_totals | + Added | Field |
| Payout totals after adjustments, under transaction.details. | |||