Skip to main content
POST
/
transactions
Create a transaction
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {quantity: 20, price_id: 'pri_01gsz91wy9k1yn7kx82aafwvea'},
      {quantity: 1, price_id: 'pri_01gsz96z29d88jrmsf2ztbfgjg'},
      {quantity: 1, price_id: 'pri_01gsz98e27ak2tyhexptwc58yk'}
    ],
    customer_id: 'ctm_01hv6y1jedq4p1n0yqn5ba3ky4',
    address_id: 'add_01hv8gq3318ktkfengj2r75gfx',
    currency_code: 'USD',
    collection_mode: 'manual',
    billing_details: {
      enable_checkout: false,
      purchase_order_number: 'PO-123',
      payment_terms: {interval: 'day', frequency: 14}
    },
    billing_period: {starts_at: '2024-04-12T00:00:00Z', ends_at: '2025-04-11T23:59:00Z'}
  })
};

fetch('https://api.paddle.com/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "data": {
    "id": "txn_01hv8m0mnx3sj85e7gxc6kga03",
    "status": "ready",
    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
    "address_id": "add_01hv8gq3318ktkfengj2r75gfx",
    "business_id": null,
    "custom_data": null,
    "origin": "api",
    "collection_mode": "manual",
    "subscription_id": null,
    "invoice_id": null,
    "invoice_number": null,
    "billing_details": {
      "enable_checkout": false,
      "payment_terms": {
        "interval": "day",
        "frequency": 14
      },
      "purchase_order_number": "PO-123",
      "additional_information": null
    },
    "billing_period": {
      "starts_at": "2024-04-12T00:00:00Z",
      "ends_at": "2025-04-11T23:59:00Z"
    },
    "currency_code": "USD",
    "discount_id": null,
    "created_at": "2024-04-12T07:40:38.007040251Z",
    "updated_at": "2024-04-12T07:40:38.007040251Z",
    "billed_at": null,
    "revised_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "description": "Annual",
          "type": "standard",
          "name": "Annual (per seat)",
          "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "50000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "status": "active",
          "created_at": "2023-02-23T13:57:54.249913Z",
          "updated_at": "2024-04-05T14:32:00.471447Z",
          "import_meta": null
        },
        "quantity": 20
      },
      {
        "price": {
          "id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
          "description": "Annual (recurring addon)",
          "type": "standard",
          "name": "Annual (recurring addon)",
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "300000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active",
          "created_at": "2023-02-23T14:00:40.265185Z",
          "updated_at": "2024-03-25T14:31:18.587603Z",
          "import_meta": null
        },
        "quantity": 1
      },
      {
        "price": {
          "id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "description": "One-time addon",
          "type": "standard",
          "name": "One-time addon",
          "product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "billing_cycle": null,
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "19900",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active",
          "created_at": "2023-02-23T14:01:28.391712Z",
          "updated_at": "2024-04-09T07:23:10.921392Z",
          "import_meta": null
        },
        "quantity": 1
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "1319900",
            "discount": "0",
            "tax": "117141",
            "total": "1437041"
          }
        }
      ],
      "totals": {
        "subtotal": "1319900",
        "tax": "117141",
        "discount": "0",
        "total": "1437041",
        "grand_total": "1437041",
        "fee": null,
        "credit": "0",
        "credit_to_balance": "0",
        "balance": "1437041",
        "earnings": null,
        "currency_code": "USD"
      },
      "adjusted_totals": {
        "subtotal": "1319900",
        "tax": "117141",
        "total": "1437041",
        "grand_total": "1437041",
        "fee": "0",
        "earnings": "0",
        "currency_code": "USD"
      },
      "payout_totals": null,
      "adjusted_payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01hv8m0n6xqk32jsq5q6pv7mpk",
          "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "quantity": 20,
          "totals": {
            "subtotal": "1000000",
            "tax": "88750",
            "discount": "0",
            "total": "1088750"
          },
          "product": {
            "id": "pro_01gsz4vmqbjk3x4vvtafffd540",
            "name": "AeroEdit Enterprise",
            "description": "The ultimate solution for organizations, featuring all Pro capabilities plus multi-user support, advanced data storage capabilities, plus personalized onboarding, dedicated account management, and the ability to pay via invoice.",
            "type": "standard",
            "tax_category": "standard",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/Ws808ziTS76a6YbnMkiK_enterprise.png",
            "custom_data": {
              "features": {
                "aircraft_performance": true,
                "compliance_monitoring": true,
                "flight_log_management": true,
                "payment_by_invoice": true,
                "route_planning": true,
                "sso": true
              },
              "suggested_addons": [],
              "upgrade_description": "Ready to reach new heights? Upgrade to enterprise to unlock single sign-on, payment by invoice, and dedicated account management."
            },
            "status": "active",
            "created_at": "2023-02-23T12:44:34.923Z",
            "updated_at": "2024-04-05T15:58:28.309Z",
            "import_meta": null
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "50000",
            "tax": "4437",
            "discount": "0",
            "total": "54437"
          }
        },
        {
          "id": "txnitm_01hv8m0n6yajavvy3q3297hd45",
          "price_id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
          "quantity": 1,
          "totals": {
            "subtotal": "300000",
            "tax": "26625",
            "discount": "0",
            "total": "326625"
          },
          "product": {
            "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
            "name": "VIP support",
            "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.",
            "type": "standard",
            "tax_category": "standard",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png",
            "custom_data": null,
            "status": "active",
            "created_at": "2023-02-23T13:58:17.615Z",
            "updated_at": "2024-04-05T15:44:02.893Z",
            "import_meta": null
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "300000",
            "tax": "26625",
            "discount": "0",
            "total": "326625"
          }
        },
        {
          "id": "txnitm_01hv8m0n6yajavvy3q376fjpht",
          "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "quantity": 1,
          "totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          },
          "product": {
            "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
            "name": "Custom domains",
            "description": "Make AeroEdit truly your own with custom domains. Custom domains reinforce your brand identity and make it easy for your team to access your account.",
            "type": "standard",
            "tax_category": "standard",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/XIG7UXoJQHmlIAiKcnkA_custom-domains.png",
            "custom_data": null,
            "status": "active",
            "created_at": "2023-02-23T14:01:02.441Z",
            "updated_at": "2024-04-05T15:43:28.971Z",
            "import_meta": null
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": null
    }
  },
  "meta": {
    "request_id": "c7db9b4e-da8c-4b05-871b-f7f47264fd72"
  }
}

Authorizations

​
Authorization
string
header
required

Requests are authenticated with API keys. Provide your API key as a Bearer token in the Authorization header.

API keys are assigned permissions, granting them access to entities and operations. Each endpoint may require one or more permissions, defined with the x-permissions extension. Values for include parameters may require specific permissions as defined in the x-enum-permissions extension. See all available permissions in the permission schema or documentation.

Get an API key and select the permissions you need from the Paddle dashboard under Paddle > Developer Tools > Authentication.

Query Parameters

​
include
enum<string>[]

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

Available options:
address,
adjustments,
adjustments_totals,
available_payment_methods,
business,
customer,
discount

Body

application/json

Represents a transaction entity when creating transactions.

​
items
(Catalog item · object | Non-catalog price for an existing product · object | Non-catalog price and product · object)[]
required

List of items to charge for. You can charge for items that you've added to your catalog by passing the Paddle ID of an existing price entity, or you can charge for non-catalog items by passing a price object.

Non-catalog items can be for existing products, or you can pass a product object as part of your price to charge for a non-catalog product.

Required array length: 1 - 100 elements

Add a catalog item to a transaction. In this case, the product and price that you're billing for exist in your product catalog in Paddle.

​
status
enum<string>

Status of this transaction. You may set a transaction to billed when creating, or omit to let Paddle set the status. Transactions are created as ready if they have an address_id, customer_id, and items, otherwise they are created as draft.

Marking as billed when creating is typically used when working with manually-collected transactions as part of an invoicing workflow. Billed transactions cannot be updated, only canceled.

Available options:
draft,
ready,
billed,
paid,
completed,
canceled,
past_due
​
customer_id
string | null

Paddle ID of the customer that this transaction is for, prefixed with ctm_. If omitted, transaction status is draft.

Example:

"ctm_01grnn4zta5a1mf02jjze7y2ys"

​
address_id
string | null

Paddle ID of the address that this transaction is for, prefixed with add_. Requires customer_id. If omitted, transaction status is draft.

Example:

"add_01gm302t81w94gyjpjpqypkzkf"

​
business_id
string | null

Paddle ID of the business that this transaction is for, prefixed with biz_. Requires customer_id.

Example:

"biz_01grrebrzaee2qj2fqqhmcyzaj"

​
custom_data
Custom data · object

Your own structured key-value data.

Example:
{ "customer_reference_id": "abcd1234" }
​
currency_code
enum<string> | null

Supported three-letter ISO 4217 currency code. Must be USD, EUR, or GBP if collection_mode is manual.

Available options:
USD,
EUR,
GBP,
JPY,
AUD,
CAD,
CHF,
HKD,
SGD,
SEK,
ARS,
BRL,
CNY,
COP,
CZK,
DKK,
HUF,
ILS,
INR,
KRW,
MXN,
NOK,
NZD,
PLN,
RUB,
THB,
TRY,
TWD,
UAH,
VND,
ZAR
Required string length: 3
​
collection_mode
enum<string>
default:automatic

How payment is collected for this transaction. automatic for checkout, manual for invoices. If omitted, defaults to automatic.

Available options:
automatic,
manual
​
discount_id
string | null

Paddle ID of the discount applied to this transaction, prefixed with dsc_.

Example:

"dsc_01gv5kpg05xp104ek2fmgjwttf"

​
billing_details
Billing details · object

Details for invoicing. Required if collection_mode is manual.

​
billing_period
Time period · object

Time period that this transaction is for. Set automatically by Paddle for subscription renewals to describe the period that charges are for.

​
checkout
TransactionCheckout · object

Paddle Checkout details for this transaction. You may pass a URL when creating or updating an automatically-collected transaction, or when creating or updating a manually-collected transaction where billing_details.enable_checkout is true.

Response

Created

​
data
TransactionIncludes · object
required

Represents a transaction entity with included entities.

​
meta
Meta · object
required

Information about this response.