API Reference

Below is a full list of the Paddle Client methods. Supported Paddle endpoints lists the Paddle API endpoints in the same order as they are in the Paddle API Reference

There are also several helper methods implimented on top of the Paddle endpoints to make usage of the API easier.

For example the pause_subscription and resume_subscription methods have been added on top of update_subscription as to pause or resume a subscription the update_subscription endpoint is used but only the pause parameter can be set (and will fail if any others are).

Supported Paddle endpoints

As listed in the Paddle API Reference

Checkout API

• Get Order Details

• Get User History

• Get Prices

Product API

• List Coupons

• Create Coupon

• Delete Coupon

• Update Coupon

• List Products

• List Transactions

• Refund Payment

Subscription API

• List Plans - (Including Get Plan)

• Create Plan

• List Subscription Users

• Cancel Subscription

• Update Subscription - (Including Pause Subscription and Resume Subscription)

• Add Modifier

• Delete Modifier

• List Modifiers

• List Payments

• Reschedule Payment

• Create One-off Charge

Alert API

• Get Webhook History

Full reference

For reference on how to use. An example on how to use List Products:

from paddle import PaddleClient

paddle = PaddleClient(vendor_id=12345, api_key='myapikey', sandbox=False)
paddle.list_products()

class paddle.PaddleClient(vendor_id=None, api_key=None, sandbox=None)

If vendor_id and api_key are not passed through when initalising Paddle will fall back and try and use environmental variables called PADDLE_VENDOR_ID and PADDLE_API_KEY

Parameters

• vendor_id (typing.Optional[int]) –

• api_key (typing.Optional[str]) –

• sandbox (typing.Optional[bool]) –

add_modifier(subscription_id, modifier_amount, modifier_recurring=True, modifier_description='')

Add Modifier Paddle docs

Parameters

• subscription_id (int) –

• modifier_amount (float) –

• modifier_recurring (bool) –

• modifier_description (str) –

Return type

dict

cancel_subscription(subscription_id)

Cancel Subscription Paddle docs

Parameters

subscription_id (int) –

Return type

bool

create_coupon(coupon_type, discount_type, discount_amount, allowed_uses, recurring, currency, product_ids=None, coupon_code=None, coupon_prefix=None, num_coupons=None, description=None, expires=None, minimum_threshold=None, group=None)

Create Coupon Paddle docs

currency appears to be required:

Paddle error 134 - The given coupon currency is invalid. The currency must match your balance currency.

Even though the docs states:

“Required if discount_amount is flat.”

Parameters

• coupon_type (str) –

• discount_type (str) –

• discount_amount (float) –

• allowed_uses (int) –

• recurring (bool) –

• currency (str) –

• product_ids (typing.Optional[list]) –

• coupon_code (typing.Optional[str]) –

• coupon_prefix (typing.Optional[str]) –

• num_coupons (typing.Optional[int]) –

• description (typing.Optional[str]) –

• expires (typing.Union[str, datetime.datetime, None]) –

• minimum_threshold (typing.Optional[int]) –

• group (typing.Optional[str]) –

Return type

dict

create_one_off_charge(subscription_id, amount, charge_name)

Create One-off Charge Paddle docs

This endpoint currently only supports x-www-form-urlencoded not json unlike most of the other Paddle endpoints

Note from Paddles API docs:

Please put a proper product / charge name here to make it clear what buyers are buying. Here are some examples:

• [add-on name] x [quantity] e.g. Supercool design plugin x 1

• [number of credits] credits for [subscription plan] e.g. 200 credits for Monthly talk time

• [quantity] [units] [product description] e.g. 124 MB data usage

Parameters

• subscription_id (int) –

• amount (float) –

• charge_name (str) –

Return type

dict

create_pay_link(product_id=None, title=None, webhook_url=None, prices=None, recurring_prices=None, trial_days=None, custom_message=None, coupon_code=None, discountable=None, image_url=None, return_url=None, quantity_variable=None, quantity=None, expires=None, affiliates=None, recurring_affiliate_limit=None, marketing_consent=None, customer_email=None, customer_country=None, customer_postcode=None, passthrough=None, vat_number=None, vat_company_name=None, vat_street=None, vat_city=None, vat_state=None, vat_country=None, vat_postcode=None)

Create Pay Link Paddle docs

product_id appears to be required:

Paddle error 108 - Unable to find requested product

Even though the docs states:

“If no product_id is set, custom non-subscription product checkouts can be generated instead by specifying title, webhook_url and prices.”

Sending an invalid coupon code will result in the request failing with “Paddle error 101 - Bad method call”

Parameters

• product_id (typing.Optional[int]) –

• title (typing.Optional[str]) –

• webhook_url (typing.Optional[str]) –

• prices (typing.Optional[typing.List[str]]) –

• recurring_prices (typing.Optional[typing.List[str]]) –

• trial_days (typing.Optional[int]) –

• custom_message (typing.Optional[str]) –

• coupon_code (typing.Optional[str]) –

• discountable (typing.Optional[bool]) –

• image_url (typing.Optional[str]) –

• return_url (typing.Optional[str]) –

• quantity_variable (typing.Optional[bool]) –

• quantity (typing.Optional[int]) –

• expires (typing.Union[str, datetime.datetime, None]) –

• affiliates (typing.Optional[typing.List[str]]) –

• recurring_affiliate_limit (typing.Optional[int]) –

• marketing_consent (typing.Optional[bool]) –

• customer_email (typing.Optional[str]) –

• customer_country (typing.Optional[str]) –

• customer_postcode (typing.Optional[str]) –

• passthrough (typing.Optional[str]) –

• vat_number (typing.Optional[str]) –

• vat_company_name (typing.Optional[str]) –

• vat_street (typing.Optional[str]) –

• vat_city (typing.Optional[str]) –

• vat_state (typing.Optional[str]) –

• vat_country (typing.Optional[str]) –

• vat_postcode (typing.Optional[str]) –

Return type

dict

create_plan(plan_name, plan_trial_days, plan_length, plan_type, main_currency_code='USD', initial_price_usd=None, initial_price_gbp=None, initial_price_eur=None, recurring_price_usd=None, recurring_price_gbp=None, recurring_price_eur=None)

Create Plan Paddle docs

In the docs all of the price variables are noted as strings except for USD which is a number. This is probably an error in the docs.

Parameters

• plan_name (str) –

• plan_trial_days (int) –

• plan_length (int) –

• plan_type (str) –

• main_currency_code (str) –

• initial_price_usd (typing.Optional[float]) –

• initial_price_gbp (typing.Optional[float]) –

• initial_price_eur (typing.Optional[float]) –

• recurring_price_usd (typing.Optional[float]) –

• recurring_price_gbp (typing.Optional[float]) –

• recurring_price_eur (typing.Optional[float]) –

Return type

dict

delete_coupon(coupon_code, product_id=None)

Delete Coupon Paddle docs

Parameters

• coupon_code (str) –

• product_id (typing.Optional[int]) –

Return type

dict

delete_modifier(modifier_id)

Delete Modifier Paddle docs

Parameters

modifier_id (int) –

Return type

dict

generate_license(product_id, allowed_uses, expires_at=None)

Generate License Paddle docs

Parameters

• product_id (int) –

• allowed_uses (int) –

• expires_at (typing.Union[str, datetime.datetime, None]) –

Return type

dict

get_order_details(checkout_id)

Get Order Details Paddle docs

Parameters

checkout_id (str) –

Return type

dict

get_plan(plan)

List Plans Paddle docs

There is no Get Plan endpoint in Paddle’s API but list plans does support sending through a plan ID. This is a helper method to get a single plan where the plan parameter is required.

Parameters

plan (int) –

Return type

dict

get_prices(product_ids, customer_country=None, customer_ip=None, coupons=None)

Get Prices Paddle docs

Parameters

• product_ids (list) –

• customer_country (typing.Optional[str]) –

• customer_ip (typing.Optional[str]) –

• coupons (typing.Optional[list]) –

Return type

dict

get_user_history(email, vendor_id=None, product_id=None)

Get User History Paddle docs

Parameters

• email (str) –

• vendor_id (typing.Optional[int]) –

• product_id (typing.Optional[int]) –

Return type

str

get_webhook_history(page=None, alerts_per_page=None, query_head=None, query_tail=None)

Get Webhook History Paddle docs

Parameters

• page (typing.Optional[int]) –

• alerts_per_page (typing.Optional[int]) –

• query_head (typing.Union[str, datetime.datetime, None]) –

• query_tail (typing.Union[str, datetime.datetime, None]) –

Return type

dict

list_coupons(product_id)

List Coupon Paddle docs

Parameters

product_id (int) –

Return type

typing.List[dict]

list_modifiers(subscription_id=None, plan_id=None)

List Modifiers Paddle docs

Parameters

• subscription_id (typing.Optional[int]) –

• plan_id (typing.Optional[int]) –

Return type

typing.List[dict]

list_plans(plan=None)

List Plans Paddle docs

Parameters

plan (typing.Optional[int]) –

Return type

typing.List[dict]

list_products()

List Products Paddle docs

Return type

dict

list_subscription_payments(subscription_id=None, plan=None, is_paid=None, _from=None, to=None, is_one_off_charge=None)

List Payment (subscription) Paddle docs

Parameters

• subscription_id (typing.Optional[int]) –

• plan (typing.Optional[int]) –

• is_paid (typing.Union[bool, int, None]) –

• _from (typing.Union[str, datetime.date, None]) –

• to (typing.Union[str, datetime.date, None]) –

• is_one_off_charge (typing.Optional[bool]) –

Return type

typing.List[dict]

list_subscription_users(subscription_id=None, plan_id=None, state=None, page=None, results_per_page=None)

List Users (subscription) Paddle docs

Note: response does not include any information in pages and totals

Parameters

• subscription_id (typing.Optional[int]) –

• plan_id (typing.Optional[int]) –

• state (typing.Optional[int]) –

• page (typing.Optional[int]) –

• results_per_page (typing.Optional[int]) –

Return type

typing.List[dict]

list_subscriptions(subscription_id=None, plan_id=None, state=None, page=None, results_per_page=None)

List Users (subscription) Paddle docs

Note: response does not include any information in pages and totals

Parameters

• subscription_id (typing.Optional[int]) –

• plan_id (typing.Optional[int]) –

• state (typing.Optional[int]) –

• page (typing.Optional[int]) –

• results_per_page (typing.Optional[int]) –

Return type

typing.List[dict]

list_transactions(entity, entity_id, page=None)

List Transations Paddle docs

Parameters

• entity (str) –

• entity_id (typing.Union[str, int]) –

• page (typing.Optional[int]) –

Return type

typing.List[dict]

pause_subscription(subscription_id)

Update Subscription Paddle docs

There is no Pause Subscription endpoint in Paddle’s API. This is a convenient helper method for update_subscription as no extra data can be sent when pausing/resuming subscriptions

Parameters

subscription_id (int) –

Return type

dict

refund_product_payment(order_id, amount=None, reason=None)

Refund Product Payment Paddle docs

Parameters

• order_id (typing.Union[str, int]) –

• amount (typing.Optional[float]) –

• reason (typing.Optional[str]) –

Return type

dict

reschedule_subscription_payment(payment_id, date)

Reschedule Payment (subscription) Paddle docs

Parameters

• payment_id (int) –

• date (typing.Union[str, datetime.date]) –

Return type

bool

resume_subscription(subscription_id)

Update Subscription Paddle docs

There is no Resume Subscription endpoint in Paddle’s API. This is a convenient helper method for update_subscription as no extra data can be sent when pausing/resuming subscriptions

Parameters

subscription_id (int) –

Return type

dict

update_coupon(coupon_code=None, new_coupon_code=None, group=None, new_group=None, product_ids=None, expires=None, allowed_uses=None, currency=None, minimum_threshold=None, discount_amount=None, recurring=None)

Update Coupon Paddle docs

Parameters

• coupon_code (typing.Optional[str]) –

• new_coupon_code (typing.Optional[str]) –

• group (typing.Optional[str]) –

• new_group (typing.Optional[str]) –

• product_ids (typing.Optional[list]) –

• expires (typing.Union[str, datetime.datetime, None]) –

• allowed_uses (typing.Optional[int]) –

• currency (typing.Optional[str]) –

• minimum_threshold (typing.Optional[int]) –

• discount_amount (typing.Optional[float]) –

• recurring (typing.Optional[bool]) –

Return type

dict

update_subscription(subscription_id, quantity=None, currency=None, recurring_price=None, bill_immediately=None, plan_id=None, prorate=None, keep_modifiers=None, passthrough=None, pause=None)

Update Subscription Paddle docs

Parameters

• subscription_id (int) –

• quantity (typing.Optional[int]) –

• currency (typing.Optional[str]) –

• recurring_price (typing.Optional[float]) –

• bill_immediately (typing.Optional[bool]) –

• plan_id (typing.Optional[int]) –

• prorate (typing.Optional[bool]) –

• keep_modifiers (typing.Optional[bool]) –

• passthrough (typing.Optional[str]) –

• pause (typing.Optional[bool]) –

Return type

dict