Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/deanpcmad/paddle

Ruby library for the Paddle API
https://github.com/deanpcmad/paddle

paddle payment-gateway payments ruby rubygem

Last synced: about 2 months ago
JSON representation

Ruby library for the Paddle API

Awesome Lists containing this project

README 

        
# Paddle Ruby Library



The easiest and most complete Ruby library for the Paddle APIs, both Classic and Billing.



## Installation



Add this line to your application's Gemfile:



```ruby

gem "paddle", "~> 2.6"

```



## Billing API



For accessing the new Billing API from Paddle. For more info, view the [Paddle Billing](https://www.paddle.com/billing) page.



### Configuration



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](https://vendors.paddle.com/authentication),

or [here for sandbox](https://sandbox-vendors.paddle.com/authentication)



```ruby

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

end

```



### Resources



The 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.



### Pagination



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:



```ruby

results = Paddle::Product.list(per_page: 10)

#=> Paddle::Collection



results.total

#=> 10



results.data

#=> [#, #]



results.each do |result|

  puts result.id

end



results.first

#=> #



results.last

#=> #



# Retrieve the next page

Paddle::Product.list(per_page: 10, after: "abc123")

#=> Paddle::Collection

```



### Caveats



>[!NOTE]

>

> 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.



### Updating records



For API endpoints that support it, you can use the `update` method to update a record, like so:



```ruby

Paddle::Product.retrieve(id: "pro_abc123").update(name: "My New Name")

```



### Products



```ruby

# 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")

```



### Prices



```ruby

# 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")

```



### Pricing Preview



```ruby

# 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")

```



### Discounts



```ruby

# 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")

```



### Customers



```ruby

# List all customers

# https://developer.paddle.com/api-reference/customers/list-customers

Paddle::Customer.list

Paddle::Customer.list(status: "active")

Paddle::Customer.list(email: "[email protected]")



# 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: "[email protected]", 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")

```



### Addresses



```ruby

# 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")

```



### Businesses



```ruby

# 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")

```



### Transactions



```ruby

# 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...

```



### Subscriptions



```ruby

# 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")

```



### Customer Portal Sessions



```ruby

# 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"]

```



### Adjustments



```ruby

# 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")

```



### Event Types



```ruby

# List all event types

Paddle::EventType.list

```



### Events



```ruby

# List all events

# https://developer.paddle.com/api-reference/events/list-events

Paddle::Event.list

```



### Notification Settings



Used for creating webhook and email notifications



```ruby

# 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")

```



### Notifications



```ruby

# 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")

```



### Reports



```ruby

# 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"}

  ]

)

```



### Webhook Simulation Types



Retrieves a list of Simulation Types - https://developer.paddle.com/api-reference/simulation-types/overview



```ruby

Paddle::SimulationType.list

```



### Webhook Simulations



```ruby

# 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")

```



## Classic API



For accessing the Paddle Classic API



### Set Client Details



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](https://vendors.paddle.com/authentication),

or [here for sandbox](https://sandbox-vendors.paddle.com/authentication)



```ruby

@client = Paddle::Classic::Client.new(

  vendor_id: "",

  vendor_auth_code: "",

  # Use the sandbox version of the API

  sandbox: true

)

```



### Plans



```ruby

# Retrieves a list of Plans

@client.plans.list

```



### Subscription Users



```ruby

# 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")

```



## Contributing



Bug reports and pull requests are welcome on GitHub at https://github.com/deanpcmad/paddle.



## License



The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).