PApaddlehq
Transactions

Create a transaction

Changed on

Creates a new transaction.

Transactions are typically created with the status of draft or ready initially:

  • Draft transactions have items against them, but don't have all of the required fields for billing. Paddle creates draft transactions automatically when a checkout is opened.
  • Paddle automatically marks transactions as ready when all of the required fields are present for billing. This includes customer_id and address_id for automatically-collected transactions, and billing_details for manually-collected transactions.

The collection_mode against a transaction determines how Paddle tries to collect for payment:

  • Manually-collected transactions are for sales-assisted billing. Paddle sends an invoice to your customer when a transaction is billed. Payment is often by wire transfer.
  • Automatically-collected transactions are for self-serve checkouts. You may pass the transaction to a checkout or use the returned checkout.url to collect for payment.

When a manually-collected transaction is marked as billed or an automatically-collected transaction is completed, Paddle automatically creates a related subscription for the items on the transaction.

If successful, your response includes a copy of the new transaction entity.

Use the include parameter to include related entities in the response.

post/transactions

Request

  • Base URL
    https://sandbox-api.paddle.com
  • Auth
    HTTP bearer

Query parameters

includeTransactionIncludeQuery[]

Include related entities in the response. Use a comma-separated list to specify multiple entities.

Request body

idstring

Unique Paddle ID for this transaction entity, prefixed with txn_.

status'draft' | 'ready' | 'billed' | 'paid' | 'completed' | 'canceled' | 'past_due'

Status of this transaction. You may set a transaction to billed or canceled, other statuses are set automatically by Paddle. Automatically-collected transactions may return completed if payment is captured successfully, or past_due if payment failed.

customer_idstring

Unique Paddle ID for this customer entity, prefixed with ctm_.

address_idstring

Unique Paddle ID for this address entity, prefixed with add_.

business_idstring

Unique Paddle ID for this business entity, prefixed with biz_.

custom_dataCustomData

Your own structured key-value data.

currency_code'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR'

Supported three-letter ISO 4217 currency code.

origin'api' | 'subscription_charge' | 'subscription_payment_method_change' | 'subscription_recurring' | 'subscription_update' | 'web'
subscription_idstring nullable

Unique Paddle ID for this subscription entity, prefixed with sub_.

invoice_idstring nullable

Paddle ID of the invoice that this transaction is related to, prefixed with inv_. Used for compatibility with the Paddle Invoice API, which is now deprecated. This field is scheduled to be removed in the next version of the Paddle API.

invoice_numberstring nullable

Invoice number for this transaction. Automatically generated by Paddle when you mark a transaction as billed where collection_mode is manual.

collection_mode'automatic' | 'manual'

How payment is collected. automatic for checkout, manual for invoices.

discount_idstring

Unique Paddle ID for this discount, prefixed with dsc_.

created_atstring date-time

RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.

updated_atstring date-time

RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

billed_atstring date-time

RFC 3339 datetime string.

Example request

{
  "id": "txn_01h04vsbhqc62t8hmd4z3b578c",
  "customer_id": "ctm_01grnn4zta5a1mf02jjze7y2ys",
  "address_id": "add_01gm302t81w94gyjpjpqypkzkf",
  "business_id": "biz_01grrebrzaee2qj2fqqhmcyzaj",
  "custom_data": {
    "customer_reference_id": "abcd1234"
  },
  "subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
  "invoice_id": "inv_01ghbk4xjn4qdsmstcwzgcgg35",
  "invoice_number": "123-45678",
  "discount_id": "dsc_01gv5kpg05xp104ek2fmgjwttf",
  "discount": {
    "custom_data": {
      "customer_reference_id": "abcd1234"
    }
  },
  "billing_period": {
    "starts_at": "2024-10-12T07:20:50.52Z",
    "ends_at": "2024-10-12T07:20:50.52Z"
  },
  "items": [
    {
      "proration": {
        "billing_period": {
          "starts_at": "2024-10-12T07:20:50.52Z",
          "ends_at": "2024-10-12T07:20:50.52Z"
        }
      },
      "price_id": "pri_01gsz8z1q1n00f12qt82y31smh"
    }
  ],
  "details": {
    "tax_rates_used": [
      {
        "tax_rate": "0.2",
        "totals": {
          "subtotal": "15000",
          "discount": "0",
          "tax": "1500",
          "total": "16500"
        }
      }
    ],
    "totals": {
      "subtotal": "15000",
      "discount": "0",
      "tax": "1500",
      "total": "16500",
      "credit": "0",
      "credit_to_balance": "0",
      "balance": "16500",
      "grand_total": "16500",
      "grand_total_tax": "83",
      "fee": "825",
      "earnings": "15675"
    },
    "adjusted_totals": {
      "subtotal": "15000",
      "tax": "1500",
      "total": "16500",
      "grand_total": "16500",
      "grand_total_tax": "83",
      "fee": "825",
      "retained_fee": "300",
      "earnings": "15675"
    },
    "payout_totals": {
      "subtotal": "15000",
      "discount": "0",
      "tax": "1500",
      "total": "16500",
      "credit": "0",
      "credit_to_balance": "0",
      "balance": "16500",
      "grand_total": "16500",
      "grand_total_tax": "83",
      "fee": "825",
      "earnings": "15675",
      "exchange_rate": "1.0513135",
      "fee_rate": "0.05"
    },
    "adjusted_payout_totals": {
      "subtotal": "15000",
      "tax": "1500",
      "total": "16500",
      "fee": "825",
      "retained_fee": "300",
      "chargeback_fee": {
        "amount": "1680",
        "original": {
          "amount": "1500"
        }
      },
      "earnings": "15675",
      "exchange_rate": "1.0513135"
    },
    "line_items": [
      {
        "price_id": "pri_01gsz8z1q1n00f12qt82y31smh",
        "proration": {
          "billing_period": {
            "starts_at": "2024-10-12T07:20:50.52Z",
            "ends_at": "2024-10-12T07:20:50.52Z"
          }
        },
        "tax_rate": "0.2",
        "unit_totals": {
          "subtotal": "15000",
          "discount": "0",
          "tax": "1500",
          "total": "16500"
        },
        "totals": {
          "subtotal": "15000",
          "discount": "0",
          "tax": "1500",
          "total": "16500"
        },
        "product": {
          "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "custom_data": {
            "customer_reference_id": "abcd1234"
          },
          "import_meta": {
            "external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
            "imported_from": "paddle_classic"
          },
          "created_at": "2024-10-12T07:20:50.52Z",
          "updated_at": "2024-10-13T07:20:50.52Z"
        },
        "id": "txnitm_01gm302t81w94gyjpjpqypkzkf"
      }
    ]
  },
  "payments": [
    {
      "payment_attempt_id": "497f776b-851d-4ebf-89ab-8ba0f75d2d6a",
      "stored_payment_method_id": "7636e781-3969-49f4-9c77-8226232e28a6",
      "payment_method_id": "paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1",
      "amount": "1050",
      "method_details": {
        "south_korea_local_card": {
          "last4": "4242"
        },
        "card": {
          "last4": "4242",
          "expiry_month": 12,
          "expiry_year": 2028
        },
        "paypal": {
          "email": "john.doe@example.com"
        }
      },
      "created_at": "2024-10-12T07:20:50.52Z",
      "captured_at": "2024-10-12T07:20:50.52Z"
    }
  ],
  "created_at": "2024-10-12T07:20:50.52Z",
  "updated_at": "2024-10-13T07:20:50.52Z",
  "billed_at": "2024-10-12T07:20:50.52Z"
}

Response

The request has succeeded and a new resource has been created as a result.

Changes

  • v1bbc0c72039c8Revision changes
    • breaking

      removed from the //// request property oneOf list

    • info

      removed from the ///// response property oneOf list for the response status

  • v14f35a8c6ea4dRevision changes
    • breaking

      removed from the ///// request property anyOf list

    • breaking

      removed from the ///// request property anyOf list

    • breaking

      added to the /////// response property oneOf list for the response status

    • breaking

      added to the ////////// response property oneOf list for the response status

    • breaking

      added to the //////// response property oneOf list for the response status

    • warning

      added the new blocked_by_policy enum value to the //// response property for the response status

    • info

      added to the ///// request property anyOf list

    • info

      added to the ///// request property anyOf list

    • info

      request property ////// deprecated

    • info

      request property /////// deprecated

    • info

      request property //////// deprecated

    • info

      added the new blocked_by_policy enum value to the request property ///

    • info

      added to the //////// request property oneOf list

    • info

      added to the //////// request property oneOf list

    • info

      response property data/payments/items/method_details/underlying_details/anyOf[subschema #1: PaymentMethodUnderlyingDetails]/korea_local/anyOf[subschema #1: Korean market underlying details]/ deprecated

    • info

      response property data/payments/items/method_details/underlying_details/anyOf[subschema #1: PaymentMethodUnderlyingDetails]/korea_local/anyOf[subschema #1: Korean market underlying details]/type deprecated

    • info

      response property data/payments/items/method_details/underlying_details/anyOf[subschema #1: PaymentMethodUnderlyingDetails]/korea_local/anyOf[subschema #1: Korean market underlying details]/type/allOf[subschema #1: Korean market underlying payment method type]/ deprecated