Docs

adjustment.created

Occurs when an adjustment is created.

Occurs when an adjustment is created. Adjustments are used to refund or credit all or part of a completed or billed transaction.

The action field describes the type of adjustment:

ActionDescription
creditCredits some or all of the related transaction. Doesn't require Paddle approval.
refundRefunds some or all of the related transaction. Most refunds for live accounts require Paddle approval and are created as pending_approval. adjustment.updated occurs when the status changes to approved or rejected.
chargeback, chargeback_warning, and relatedCreated automatically by Paddle when a customer disputes a charge with their payment provider.
event_idstringrequired
Example: evt_01gks14ge726w50ch2tmaw2a1x
Unique Paddle ID for this event, prefixed with evt_.
Pattern: ^evt_[a-z\d]{26}$
event_typestringrequired
Type of event sent by Paddle, in the format entity.event_type.
Values
+ Show all values
occurred_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this event occurred.
notification_idstringrequired
Example: ntf_01ghbkd0frb9k95cnhwd1bxpvk
Unique Paddle ID for this notification, prefixed with ntf_.
Pattern: ^ntf_[a-z\d]{26}$
dataobjectrequired
New or changed entity.
idstringrequired
Example: adj_01ghvjt9dbpnndeqjve8cktgqs
Reference for the adjustment
Pattern: ^adj_[a-z\d]{26}$
actionstringrequired
This parameter indicates the type of adjustment that will be created. Partial and full refunds can be requested, but needs approval from Paddle. Tax refunds, chargeback and chargeback_warning are reserved for Paddle internal users.
Values
  • credit
    Credits some or all the related transaction.
  • refund
    Refunds some or all the related transaction. Must be approved by Paddle in most cases.
  • chargeback
    Chargeback for the related transaction. Automatically created by Paddle when a customer successfully disputes a charge.
  • chargeback_reverse
    Reversal of a chargeback for the related transaction. Automatically created by Paddle when Paddle contests a chargeback successfully.
  • chargeback_warning
    Warning of an upcoming chargeback for the related transaction. Automatically created by Paddle.
+ Show all values
  • chargeback_warning_reverse
    Reversal of a chargeback warning for the related transaction. Automatically created by Paddle.
  • credit_reverse
    Reversal of a credit for the related transaction. Automatically created by Paddle.
typestring | nullrequired
Example: partial
Type of adjustment. Use full to adjust the grand total for the related transaction. Include an items array when creating a partial adjustment. If omitted, defaults to partial.
Values
  • full
    The grand total for the related transaction is adjusted.
  • partial
    Some line items for the related transaction are adjusted. Requires items.
transaction_idstringrequired
Example: txn_01ghvjq8hbjyf4cyfkqxa676pq
ID of the Transaction that this adjustment belongs to
Pattern: ^txn_[a-z\d]{26}$
subscription_idstring | nullrequired
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Unique Paddle ID for this subscription entity, prefixed with sub_.
Pattern: ^sub_[a-z\d]{26}$
customer_idstringrequired
Example: ctm_01ghbm8g2qxsjp07p5ywsy61cs
ID of the Customer that this Transaction is for
Pattern: ^ctm_[a-z\d]{26}$
reasonstringrequired
Some context on why the adjustment is being performed
credit_applied_to_balanceboolean | nullrequired
When the Transaction collection mode is manual and the status is billed, this field is false. If it is true, it indicates that credits have been applied to the customer's balance. Otherwise, the adjustment is used to decrease the total amount of a billed invoice Transaction.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
statusstringrequired
Status for an adjustment. Pending approval is read-only and cannot be set. Approved and Rejected are both final states for an adjustment.
Values
  • pending_approval
    Adjustment is pending approval by Paddle. Most refunds for live accounts must be approved by Paddle.
  • approved
    Adjustment is approved. Default for credits. Set when Paddle approves a refund that was pending_approval.
  • rejected
    Adjustment has been rejected. Set when Paddle rejects a refund that was pending_approval.
  • reversed
    Adjustment has been reversed. Set by Paddle when a chargeback_reversal or credit_reversal adjustment is created for this adjustment.
itemsarrayrequired
idstringrequired
Example: adjitm_01gw4rs4kex0prncwfne87ft8x
Unique Paddle ID for this adjustment item, prefixed with adjitm_.
Pattern: ^adjitm_[a-z\d]{26}$
item_idstringrequired
Example: txnitm_01gm302t81w94gyjpjpqypkzkf
Paddle ID for the transaction item that this adjustment item relates to, prefixed with txnitm_.
Pattern: ^txnitm_[a-z\d]{26}$
typestringrequired
Example: full
Type of adjustment for this transaction item. tax adjustments are automatically created by Paddle. Include amount when creating a partial adjustment.
Values
  • full
    Full total for this transaction item is adjusted.
  • partial
    Part of this transaction item is adjusted. Include amount to specify the partial amount adjusted.
  • tax
    Tax for this transaction item is adjusted. Created automatically by Paddle.
  • proration
    A prorated amount for this transaction item is adjusted. Created automatically by Paddle in some cases when making changes to a subscription.
amountstring | nullrequired
Amount adjusted for this transaction item. Required when item type is partial.
prorationobject | nullrequired
How proration was calculated for this item. Populated when a transaction is created from a subscription change, where proration_billing_mode was prorated_immediately or prorated_next_billing_period. Set automatically by Paddle.
ratestringrequired
Rate used to calculate proration.
billing_periodobjectrequired
Billing period that proration is based on.
starts_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this period ends.
totalsobjectrequired
Breakdown of the total for an adjustment item.
subtotalstringrequired
Example: 15000
Amount multiplied by quantity.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
totalsobjectrequired
Breakdown of the total for an adjustment.
subtotalstringrequired
Example: 15000
Total before tax. For tax adjustments, the value is 0.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
feestringrequired
Example: 300
Total fee taken by Paddle for this adjustment.
retained_feestring
Example: 300
Paddle fees retained for this adjustment.
earningsstringrequired
Example: 14700
Total earnings. This is the subtotal minus the Paddle fee. For tax adjustments, this value is negative, which means a positive effect in the transaction earnings. This is because the fee is originally calculated from the transaction total, so if a tax adjustment is made, then the fee portion of it is returned.
currency_codestringrequired
Example: USD
Three-letter ISO 4217 currency code used for this adjustment.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
payout_totalsobject | nullrequired
Breakdown of how this adjustment affects your payout balance.
subtotalstringrequired
Example: 15000
Adjustment total before tax and fees.
taxstringrequired
Example: 1500
Total tax on the adjustment subtotal.
totalstringrequired
Example: 16500
Adjustment total after tax.
feestringrequired
Example: 300
Adjusted Paddle fee.
retained_feestringrequired
Example: 300
Paddle fees retained for this adjustment.
chargeback_feeobject
Chargeback fees incurred for this adjustment. Only returned when the adjustment action is chargeback or chargeback_warning.
amountstringrequired
Example: 1680
Chargeback fee converted into the payout currency.
originalobject | nullrequired
Chargeback fee before conversion to the payout currency. null when the chargeback fee is the same as the payout currency.
amountstringrequired
Example: 1500
Fee amount for this chargeback in the original currency.
currency_codestringrequired
Example: USD
Three-letter ISO 4217 currency code for the original chargeback fee.
Values
  • AUD
    Australian Dollar
  • CAD
    Canadian Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • USD
    United States Dollar
earningsstringrequired
Example: 15120
Adjusted payout earnings. This is the adjustment total plus adjusted Paddle fees, excluding chargeback fees.
currency_codestringrequired
Three-letter ISO 4217 currency code used for the payout for this transaction. If your primary currency has changed, this reflects the primary currency at the time the transaction was billed.
Values
  • AUD
    Australian Dollar
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • CNY
    Chinese Yuan
  • CZK
    Czech Koruna
+ Show all values
  • DKK
    Danish Krone
  • EUR
    Euro
  • GBP
    Pound Sterling
  • HUF
    Hungarian Forint
  • PLN
    Polish Zloty
  • SEK
    Swedish Krona
  • USD
    United States Dollar
  • ZAR
    South African Rand
tax_rates_usedarray | nullrequired
tax_ratestringrequired
Example: 0.2
Rate used to calculate tax for this adjustment.
totalsobjectrequired
Calculated totals for the tax applied to this adjustment.
subtotalstringrequired
Example: 15000
Total before tax. For tax adjustments, the value is 0.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
created_atstring (date-time)required
Example: 2019-10-12T07:20:50.52Z
Timestamp following the RFC 3339 standard. This is set by the system, and cannot be changed via the API.
updated_atstring (date-time)required
Example: 2019-10-12T07:20:50.52Z
Timestamp following the RFC 3339 standard. This is set by the system, and cannot be changed via the API.
adjustment.created
{
  "event_id": "evt_01hvgf2skkg8dsk5dczemw2bx1",
  "event_type": "adjustment.created",
  "occurred_at": "2024-04-15T08:48:20.595926Z",
  "notification_id": "ntf_01hvgf2spk3bvewnw8t2zrnbmb",
  "data": {
    "id": "adj_01hvgf2s84dr6reszzg29zbvcm",
    "items": [
      {
        "id": "adjitm_01hvgf2s84dr6reszzg2gx70gj",
        "type": "partial",
        "amount": "100",
        "totals": {
          "tax": "8",
          "total": "100",
          "subtotal": "92"
        },
        "item_id": "txnitm_01hvcc94b7qgz60qmrqmbm19zw",
        "proration": null
      }
    ],
    "action": "refund",
    "type": "partial",
    "reason": "error",
    "status": "pending_approval",
    "totals": {
      "fee": "5",
      "tax": "8",
      "total": "100",
      "earnings": "87",
      "subtotal": "92",
      "currency_code": "USD",
      "retained_fee": "5"
    },
    "created_at": "2024-04-15T08:48:20.239695Z",
    "updated_at": "2024-04-15T08:48:20.239695Z",
    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
    "currency_code": "USD",
    "payout_totals": {
      "fee": "5",
      "tax": "8",
      "total": "100",
      "earnings": "87",
      "subtotal": "92",
      "currency_code": "USD",
      "retained_fee": "5",
      "chargeback_fee": {
        "amount": "0",
        "original": null
      }
    },
    "transaction_id": "txn_01hvcc93znj3mpqt1tenkjb04y",
    "subscription_id": "sub_01hvccbx32q2gb40sqx7n42430",
    "credit_applied_to_balance": null,
    "tax_rates_used": null
  }
}

Was this page helpful?