The easiest and most complete Ruby library for the Paddle APIs, both Classic and Billing.
Add this line to your application's Gemfile:
gem "paddle", "~> 2.6"For accessing the new Billing API from Paddle. For more info, view the Paddle Billing page.
Firstly you'll need to generate and set your API Key and the environment.
You can find and generate an API key here for production, or here for sandbox
Paddle.configure do |config|
# Use :development or :sandbox for the Sandbox API
# Or use :production for the Production API
config.environment = :sandbox
config.api_key = ENV["PADDLE_API_KEY"]
# Set the API version. Defaults to 1
config.version = 1
endThe gem maps as closely as we can to the Paddle API so you can easily convert API examples to gem code.
Responses are created as objects like Paddle::Product. Having types like Paddle::Product is handy for understanding what
type of object you're working with. They're built using OpenStruct so you can easily access data in a Ruby-ish way.
Some of the endpoints return pages of results. The result object will have a data key to access the results.
An example of using collections, including pagination:
results = Paddle::Product.list(per_page: 10)
#=> Paddle::Collection
results.total
#=> 10
results.data
#=> [#<Paddle::Product>, #<Paddle::Product>]
results.each do |result|
puts result.id
end
results.first
#=> #<Paddle::Product>
results.last
#=> #<Paddle::Product>
# Retrieve the next page
Paddle::Product.list(per_page: 10, after: "abc123")
#=> Paddle::CollectionNote
The Paddle API doesn't take nil values for optional parameters. If you want to remove a value, you'll need to pass "null" instead.
For API endpoints that support it, you can use the update method to update a record, like so:
Paddle::Product.retrieve(id: "pro_abc123").update(name: "My New Name")# List all products
# https://developer.paddle.com/api-reference/products/list-products
Paddle::Product.list
Paddle::Product.list(status: "active")
Paddle::Product.list(status: "archived")
Paddle::Product.list(tax_category: "saas")
# Create a product
# https://developer.paddle.com/api-reference/products/create-product
Paddle::Product.create(name: "My SAAS Plan", tax_category: "saas")
Paddle::Product.create(name: "My Standard Product", tax_category: "standard")
# Retrieve a product
product = Paddle::Product.retrieve(id: "pro_abc123")
# Update a product
# https://developer.paddle.com/api-reference/products/update-product
product.update(description: "This is a plan")
# or
Paddle::Product.update(id: "pro_abc123", description: "This is a plan")# List all prices
# https://developer.paddle.com/api-reference/prices/list-prices
Paddle::Price.list
Paddle::Price.list(status: "active")
Paddle::Price.list(status: "archived")
Paddle::Price.list(product_id: "pro_abc123")
# Create a price
# Note that unit_price amount should be a string
# https://developer.paddle.com/api-reference/prices/create-price
Paddle::Price.create(product_id: "pro_abc123", description: "A one off price", amount: "1000", currency: "GBP")
# Retrieve a price
price = Paddle::Price.retrieve(id: "pri_123abc")
# Update a price
# https://developer.paddle.com/api-reference/prices/update-price
price.update(description: "An updated description")
# or
Paddle::Price.update(id: "pri_123abc", description: "An updated description")# Preview calculations for one or more prices
# This is normally used when building pricing pages
# https://developer.paddle.com/api-reference/pricing-preview/preview-prices
Paddle::PricingPreview.generate(items: [ { price_id: "pri_123abc", quantity: 5 } ])
Paddle::PricingPreview.generate(items: [ { price_id: "pri_123abc", quantity: 5 } ], currency_code: "GBP")
Paddle::PricingPreview.generate(items: [ { price_id: "pri_123abc", quantity: 5 } ], customer_ip_address: "1.1.1.1")# List all discounts
# https://developer.paddle.com/api-reference/discounts/list-discounts
Paddle::Discount.list
Paddle::Discount.list(status: "active")
# Create a discount
# Note that amount should be a string
# https://developer.paddle.com/api-reference/discounts/create-discount
Paddle::Discount.create(description: "$5 off", type: "flat", amount: "500", currency_code: "USD")
Paddle::Discount.create(description: "10% Off", type: "percentage", amount: "10", code: "10OFF")
# Retrieve a discount
discount = Paddle::Discount.retrieve(id: "dsc_abc123")
# Update a discount
# https://developer.paddle.com/api-reference/discounts/update-discount
discount.update(description: "An updated description")
# or
Paddle::Discount.update(id: "dsc_abc123", description: "An updated description")# List all customers
# https://developer.paddle.com/api-reference/customers/list-customers
Paddle::Customer.list
Paddle::Customer.list(status: "active")
Paddle::Customer.list(email: "me@mydomain.com")
# Create a customer
# https://developer.paddle.com/api-reference/customers/create-customer
# Returns a Paddle::Errors::ConflictError if the email is already used on Paddle
Paddle::Customer.create(email: "myemail@mydomain.com", name: "Customer Name")
# Retrieve a customer
customer = Paddle::Customer.retrieve(id: "ctm_abc123")
# Update a customer
# https://developer.paddle.com/api-reference/customers/update-customer
customer.update(status: "archived")
# or
Paddle::Customer.update(id: "ctm_abc123", status: "archived")
# Retrieve credit balance for a customer
# https://developer.paddle.com/api-reference/customers/list-credit-balances
Paddle::Customer.credit(id: "ctm_abc123")# List all addresses for a customer
# https://developer.paddle.com/api-reference/addresses/list-addresses
Paddle::Address.list(customer: "ctm_abc123")
# Create an address
# https://developer.paddle.com/api-reference/addresses/create-address
Paddle::Address.create(customer: "ctm_abc123", country_code: "GB", postal_code: "SW1A 2AA")
# Retrieve an address
address = Paddle::Address.retrieve(customer: "ctm_abc123", id: "add_abc123")
# Update an address
# https://developer.paddle.com/api-reference/addresses/update-address
address.update(status: "archived")
# or
Paddle::Address.update(customer: "ctm_abc123", id: "add_abc123", status: "archived")# List all businesses for a customer
# https://developer.paddle.com/api-reference/businesses/list-businesses
Paddle::Business.list(customer: "ctm_abc123")
# Create a business
# https://developer.paddle.com/api-reference/businesses/create-business
Paddle::Business.create(customer: "ctm_abc123", name: "My Ltd Company")
# Retrieve a business
business = Paddle::Business.retrieve(customer: "ctm_abc123", id: "biz_abc123")
# Update a business
# https://developer.paddle.com/api-reference/businesses/update-business
business.update(status: "archived")
# or
Paddle::Business.update(customer: "ctm_abc123", id: "biz_abc123", status: "archived")# List all transactions
# https://developer.paddle.com/api-reference/transactions/list-transactions
Paddle::Transaction.list(customer_id: "ctm_abc123")
Paddle::Transaction.list(subscription_id: "sub_abc123")
Paddle::Transaction.list(status: "completed")
# Create a transaction
# https://developer.paddle.com/api-reference/transactions/create-transaction
Paddle::Transaction.create(items: [ { price_id: "pri_abc123", quantity: 1 } ])
# Retrieve a transaction
Paddle::Transaction.retrieve(id: "txn_abc123")
# Retrieve a transaction with extra information
# extra can be either "address", "adjustment", "adjustments_totals", "business", "customer", "discount"
transaction = Paddle::Transaction.retrieve(id: "txn_abc123", extra: "customer")
# Update a transaction
# https://developer.paddle.com/api-reference/transaction/update-transaction
transaction.update(items: [ { price_id: "pri_abc123", quantity: 2 } ])
# or
Paddle::Transaction.update(id: "txn_abc123", items: [ { price_id: "pri_abc123", quantity: 2 } ])
# Preview a transaction
# https://developer.paddle.com/api-reference/transaction/preview-transaction
Paddle::Transaction.preview(items: [ { price_id: "pri_123abc", quantity: 5 } ])
# Get a PDF invoice for a transaction
# disposition defaults to "attachment"
# Returns a raw URL. This URL is not permanent and will expire.
# https://developer.paddle.com/api-reference/transaction/get-invoice-pdf
Paddle::Transaction.invoice(id: "txn_abc123", disposition: "inline")
#=> https://paddle-sandbox-invoice...# List all subscriptions
# https://developer.paddle.com/api-reference/subscriptions/list-subscriptions
Paddle::Subscription.list(customer_id: "ctm_abc123")
Paddle::Subscription.list(price_id: "pri_abc123")
Paddle::Subscription.list(status: "active")
Paddle::Subscription.list(status: "canceled")
Paddle::Subscription.list(collection_mode: "automatic")
Paddle::Subscription.list(scheduled_change_action: "cancel")
# Retrieve a subscription
Paddle::Subscription.retrieve(id: "sub_abc123")
# Retrieve a subscription with extra information
# extra can be either "next_transaction" or "recurring_transaction_details"
subscription = Paddle::Subscription.retrieve(id: "sub_abc123", extra: "next_transaction")
# Preview an update to a subscription
# https://developer.paddle.com/api-reference/subscriptions/preview-subscription
Paddle::Subscription.preview(id: "sub_abc123", items: [ { price_id: "pri_123abc", quantity: 2 } ])
# Update a subscription
# https://developer.paddle.com/api-reference/subscriptions/update-subscription
subscription.update(billing_details: {purchase_order_number: "PO-1234"})
# or
Paddle::Subscription.update(id: "sub_abc123", billing_details: {purchase_order_number: "PO-1234"})
# Get a transaction to update payment method
# https://developer.paddle.com/api-reference/subscriptions/update-payment-method
Paddle::Subscription.get_transaction(id: "sub_abc123")
# Create a one-time charge for a subscription
# https://developer.paddle.com/api-reference/subscriptions/create-one-time-charge
Paddle::Subscription.charge(id: "sub_abc123", items: [ { price_id: "pri_123abc", quantity: 2 } ], effective_from: "immediately")
# Pause a subscription
# https://developer.paddle.com/api-reference/subscriptions/pause-subscription
Paddle::Subscription.pause(id: "sub_abc123")
Paddle::Subscription.pause(id: "sub_abc123", effective_from: "next_billing_period")
Paddle::Subscription.pause(id: "sub_abc123", effective_from: "immediately")
# Resume a paused subscription
# https://developer.paddle.com/api-reference/subscriptions/resume-subscription
Paddle::Subscription.resume(id: "sub_abc123", effective_from: "next_billing_period")
Paddle::Subscription.resume(id: "sub_abc123", effective_from: "immediately")
# Cancel a subscription
# https://developer.paddle.com/api-reference/subscriptions/cancel-subscription
Paddle::Subscription.cancel(id: "sub_abc123", effective_from: "next_billing_period")
Paddle::Subscription.cancel(id: "sub_abc123", effective_from: "immediately")
# Activate a trialing subscription
# https://developer.paddle.com/api-reference/subscriptions/activate-subscription
Paddle::Subscription.activate(id: "sub_abc123")# Create a Customer Portal Session
# https://developer.paddle.com/api-reference/customer-portals/create-customer-portal-session
Paddle::PortalSession.create customer: "ctm_abc123"
Paddle::PortalSession.create customer: "ctm_abc123", subscription_ids: ["sub_abc123"]# List all adjustments
# https://developer.paddle.com/api-reference/adjustments/list-adjustments
Paddle::Adjustment.list(subscription_id: "sub_abc123")
Paddle::Adjustment.list(transaction_id: "txn_abc123")
Paddle::Adjustment.list(action: "refund")
# Create an adjustment
# https://developer.paddle.com/api-reference/adjustments/create-adjustment
Paddle::Adjustment.create(
action: "refund",
transaction_id: "txn_abc123",
reason: "Requested by customer",
items: [
{
type: "full",
item_id: "txnitm_anc123"
}
]
)
# Get a credit note for an adjustment
# disposition defaults to "attachment"
# Returns a raw URL. This URL is not permanent and will expire.
# https://developer.paddle.com/api-reference/adjustments/get-credit-note-pdf
Paddle::Adjustment.credit_note(id: "adj_abc123", disposition: "inline")# List all event types
Paddle::EventType.list# List all events
# https://developer.paddle.com/api-reference/events/list-events
Paddle::Event.listUsed for creating webhook and email notifications
# List all notification settings
Paddle::NotificationSetting.list
# Retrieve a notification setting
setting = Paddle::NotificationSetting.retrieve(id: "ntfset_abc123")
# Create a notification setting
# https://developer.paddle.com/api-reference/notification-settings/create-notification-setting
Paddle::NotificationSetting.create(
description: "Webhook for App",
destination: "https://myapp.com/webhook",
type: "webhook",
subscribed_events: [
"subscription.activated",
"transaction.completed"
]
)
# Update a notification setting
# https://developer.paddle.com/api-reference/notification-settings/update-notification-setting
setting.update(subscribed_events: %w[subscription.activated transaction.completed transaction.billed])
# or
Paddle::NotificationSetting.update(id: "ntfset_abc123",
subscribed_events: [
"subscription.activated",
"transaction.completed",
"transaction.billed"
]
)
# Delete a notification setting
Paddle::NotificationSetting.delete(id: "ntfset_abc123")# List all notifications
Paddle::Notification.list
Paddle::Notification.list(notification_setting_id: "ntfset_abc123")
Paddle::Notification.list(status: "delivered")
Paddle::Notification.list(status: "failed")
# Retrieve a notification
Paddle::Notification.retrieve(id: "ntf_abc123")
# Replay a notification
# Attempts to resend a notification
# (currently not working)
Paddle::Notification.replay(id: "ntf_abc123")
# List all logs for a notification
# https://developer.paddle.com/api-reference/notifications/list-notification-logs
Paddle::Notification.logs(id: "ntf_abc123")# List all reports
Paddle::Report.list
# Retrieve a report
Paddle::Report.retrieve(id: "rpt_abc123")
# Get CSV download link for a report
# Returns a raw URL. This URL is not permanent and will expire.
# https://developer.paddle.com/api-reference/reports/get-report-csv
Paddle::Report.csv(id: "rpt_abc123")
# Create a Report
# https://developer.paddle.com/api-reference/reports/create-report
Paddle::Report.create(
type: "transactions",
filters: [
{name: "updated_at", operator: "lt", value: "2024-04-30"},
{name: "updated_at", operator: "gte", value: "2024-04-01"}
]
)Retrieves a list of Simulation Types - https://developer.paddle.com/api-reference/simulation-types/overview
Paddle::SimulationType.list# List all simulations
Paddle::Simulation.list
Paddle::Simulation.list(status: "archived")
Paddle::Simulation.list(notification_setting_id: "nftset_abc123")
# Create a simulation
# https://developer.paddle.com/api-reference/simulations/create-simulation
Paddle::Simulation.create(notification_setting_id: "ntfset_abc123", name: "Customer Create", type: "customer.completed")
Paddle::Simulation.create(notification_setting_id: "ntfset_abc123", name: "Subscription Created", type: "subscription_creation")
# Retrieve a simulation
Paddle::Simulation.retrieve(id: "ntfsim_abc123")
# Update a simulation
# https://developer.paddle.com/api-reference/simulations/update-simulation
Paddle::Simulation.update(id: "ntfsim_abc123", name: "Simulation 2")
Paddle::Simulation.update(id: "ntfsim_abc123", status: "archived")
# List all simulation runs
Paddle::Simulation.runs(id: "ntfsim_abc123")
# Create a simulation run
# https://developer.paddle.com/api-reference/simulations/create-simulation-run
Paddle::SimulationRun.create(simulation_id: "ntfsim_abc123")
# Retrieve a simulation run
Paddle::SimulationRun.retrieve(simulation_id: "ntfsim_abc123", id: "ntfsimrun_abc123")
# List all simulation run events
Paddle::SimulationRun.events(simulation_id: "ntfsim_abc123", run_id: "ntfsimrun_abc123")
# Replay a simulation run event
# https://developer.paddle.com/api-reference/simulations/replay-simulation-run-event
Paddle::SimulationRunEvent.replay(simulation_id: "ntfsim_abc123", run_id: "ntfsimrun_abc123", id: "ntfsimevt_abc123")For accessing the Paddle Classic API
Firstly you'll need to set your Vendor ID, Vendor Auth Code and if you want to use the Sandbox API or not.
You can find your vendor details here for production, or here for sandbox
@client = Paddle::Classic::Client.new(
vendor_id: "",
vendor_auth_code: "",
# Use the sandbox version of the API
sandbox: true
)# Retrieves a list of Plans
@client.plans.list# List all users subscribed to any plan
@client.users.list
@client.users.list(subscription_id: "abc123")
@client.users.list(plan_id: "abc123")
@client.users.list(state: "active")
@client.users.list(state: "deleted")
# Update a user's subscription
# https://developer.paddle.com/api-reference/e3872343dfbba-update-user
@client.users.update(subscription_id: "abc123")
# Pause a user's subscription
@client.users.pause(subscription_id: "abc123")
# Unpause a user's subscription
@client.users.unpause(subscription_id: "abc123")
# Update the Postcode/ZIP Code of a user's subscription
@client.users.update_postcode(subscription_id: "abc123", postcode: "123abc")
# Cancel a user's subscription
@client.users.cancel(subscription_id: "abc123")Bug reports and pull requests are welcome on GitHub at https://github.com/deanpcmad/paddle.
The gem is available as open source under the terms of the MIT License.
