billingio 1.0.0 → 2.0.0

data/lib/billingio/models/payout_intent.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a payout intent (withdrawal request).
+  #
+  # @attr_reader payout_id        [String]      unique identifier (prefixed +po_+)
+  # @attr_reader amount_usd       [Float]       payout amount in USD
+  # @attr_reader chain            [String]      blockchain network
+  # @attr_reader token            [String]      stablecoin token
+  # @attr_reader destination      [String]      destination wallet address
+  # @attr_reader tx_hash          [String, nil] on-chain transaction hash
+  # @attr_reader status           [String]      payout status
+  # @attr_reader metadata         [Hash, nil]   arbitrary key-value pairs
+  # @attr_reader executed_at      [String, nil] ISO-8601 execution timestamp
+  # @attr_reader created_at       [String]      ISO-8601 creation timestamp
+  # @attr_reader updated_at       [String]      ISO-8601 last-update timestamp
+  class PayoutIntent
+    ATTRS = %i[
+      payout_id amount_usd chain token destination
+      tx_hash status metadata
+      executed_at created_at updated_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::PayoutIntent]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::PayoutIntent payout_id=#{@payout_id.inspect} amount_usd=#{@amount_usd.inspect} status=#{@status.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/revenue_event.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a revenue event for reporting.
+  #
+  # @attr_reader revenue_event_id [String]      unique identifier (prefixed +rev_+)
+  # @attr_reader type             [String]      event type (e.g. "payment", "refund")
+  # @attr_reader amount_usd       [Float]       revenue amount in USD
+  # @attr_reader customer_id      [String, nil] related customer
+  # @attr_reader checkout_id      [String, nil] related checkout
+  # @attr_reader subscription_id  [String, nil] related subscription
+  # @attr_reader metadata         [Hash, nil]   arbitrary key-value pairs
+  # @attr_reader occurred_at      [String]      ISO-8601 event timestamp
+  # @attr_reader created_at       [String]      ISO-8601 creation timestamp
+  class RevenueEvent
+    ATTRS = %i[
+      revenue_event_id type amount_usd
+      customer_id checkout_id subscription_id
+      metadata occurred_at created_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::RevenueEvent]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::RevenueEvent revenue_event_id=#{@revenue_event_id.inspect} type=#{@type.inspect} amount_usd=#{@amount_usd.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/settlement.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a payout settlement record.
+  #
+  # @attr_reader settlement_id [String]      unique identifier (prefixed +stl_+)
+  # @attr_reader payout_id     [String]      parent payout intent
+  # @attr_reader amount_usd    [Float]       settled amount in USD
+  # @attr_reader fee_usd       [Float]       fee amount in USD
+  # @attr_reader net_usd       [Float]       net amount in USD
+  # @attr_reader chain         [String]      blockchain network
+  # @attr_reader token         [String]      stablecoin token
+  # @attr_reader tx_hash       [String, nil] on-chain transaction hash
+  # @attr_reader status        [String]      settlement status
+  # @attr_reader settled_at    [String, nil] ISO-8601 settlement timestamp
+  # @attr_reader created_at    [String]      ISO-8601 creation timestamp
+  class Settlement
+    ATTRS = %i[
+      settlement_id payout_id amount_usd fee_usd net_usd
+      chain token tx_hash status
+      settled_at created_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::Settlement]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::Settlement settlement_id=#{@settlement_id.inspect} amount_usd=#{@amount_usd.inspect} status=#{@status.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/subscription.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents an active subscription.
+  #
+  # @attr_reader subscription_id        [String]      unique identifier (prefixed +sub_+)
+  # @attr_reader customer_id            [String]      owning customer
+  # @attr_reader plan_id                [String]      associated plan
+  # @attr_reader status                 [String]      subscription status
+  # @attr_reader current_period_start   [String, nil] ISO-8601 current period start
+  # @attr_reader current_period_end     [String, nil] ISO-8601 current period end
+  # @attr_reader canceled_at            [String, nil] ISO-8601 cancellation timestamp
+  # @attr_reader metadata               [Hash, nil]   arbitrary key-value pairs
+  # @attr_reader created_at             [String]      ISO-8601 creation timestamp
+  # @attr_reader updated_at             [String]      ISO-8601 last-update timestamp
+  class Subscription
+    ATTRS = %i[
+      subscription_id customer_id plan_id status
+      current_period_start current_period_end
+      canceled_at metadata created_at updated_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::Subscription]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::Subscription subscription_id=#{@subscription_id.inspect} plan_id=#{@plan_id.inspect} status=#{@status.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/subscription_plan.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a subscription plan template.
+  #
+  # @attr_reader plan_id        [String]      unique identifier (prefixed +plan_+)
+  # @attr_reader name           [String]      human-readable plan name
+  # @attr_reader amount_usd     [Float]       recurring amount in USD
+  # @attr_reader interval       [String]      billing interval (e.g. "monthly", "yearly")
+  # @attr_reader interval_count [Integer]     number of intervals between billings
+  # @attr_reader chain          [String, nil] blockchain network
+  # @attr_reader token          [String, nil] stablecoin token
+  # @attr_reader metadata       [Hash, nil]   arbitrary key-value pairs
+  # @attr_reader status         [String]      plan status
+  # @attr_reader created_at     [String]      ISO-8601 creation timestamp
+  # @attr_reader updated_at     [String]      ISO-8601 last-update timestamp
+  class SubscriptionPlan
+    ATTRS = %i[
+      plan_id name amount_usd interval interval_count
+      chain token metadata status
+      created_at updated_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::SubscriptionPlan]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::SubscriptionPlan plan_id=#{@plan_id.inspect} name=#{@name.inspect} amount_usd=#{@amount_usd.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/subscription_renewal.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a subscription renewal attempt.
+  #
+  # @attr_reader renewal_id      [String]      unique identifier (prefixed +ren_+)
+  # @attr_reader subscription_id [String]      parent subscription
+  # @attr_reader status          [String]      renewal status
+  # @attr_reader amount_usd      [Float]       renewal amount in USD
+  # @attr_reader attempt_count   [Integer]     number of attempts made
+  # @attr_reader next_retry_at   [String, nil] ISO-8601 next retry timestamp
+  # @attr_reader checkout_id     [String, nil] checkout created for this renewal
+  # @attr_reader created_at      [String]      ISO-8601 creation timestamp
+  # @attr_reader updated_at      [String]      ISO-8601 last-update timestamp
+  class SubscriptionRenewal
+    ATTRS = %i[
+      renewal_id subscription_id status amount_usd
+      attempt_count next_retry_at checkout_id
+      created_at updated_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::SubscriptionRenewal]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::SubscriptionRenewal renewal_id=#{@renewal_id.inspect} subscription_id=#{@subscription_id.inspect} status=#{@status.inspect}>"
+    end
+  end
+end

data/lib/billingio/resources/adjustments.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Provides access to revenue adjustment endpoints.
+  #
+  #   client.adjustments.list
+  #   client.adjustments.create(type: "credit", amount_usd: 10.00, reason: "Goodwill credit")
+  class Adjustments
+    # @api private
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    # List adjustments with cursor-based pagination.
+    #
+    # @param cursor      [String, nil] opaque cursor for the next page
+    # @param limit       [Integer]     items per page (1..100, default 25)
+    # @param customer_id [String, nil] filter by customer
+    # @return [BillingIO::PaginatedList<BillingIO::Adjustment>]
+    # @raise [BillingIO::Error]
+    def list(cursor: nil, limit: 25, customer_id: nil)
+      params = { limit: limit }
+      params[:cursor]      = cursor      if cursor
+      params[:customer_id] = customer_id if customer_id
+
+      data = @http.get("/revenue/adjustments", params)
+      PaginatedList.from_hash(data, Adjustment)
+    end
+
+    # Create a new revenue adjustment.
+    #
+    # @param type        [String]      adjustment type ("credit", "debit", "correction")
+    # @param amount_usd  [Float]       adjustment amount in USD
+    # @param reason      [String, nil] human-readable reason
+    # @param customer_id [String, nil] related customer
+    # @param metadata    [Hash, nil]   arbitrary key-value pairs
+    # @return [BillingIO::Adjustment]
+    # @raise [BillingIO::Error]
+    def create(type:, amount_usd:, reason: nil, customer_id: nil, metadata: nil)
+      body = {
+        "type"       => type,
+        "amount_usd" => amount_usd
+      }
+      body["reason"]      = reason      if reason
+      body["customer_id"] = customer_id if customer_id
+      body["metadata"]    = metadata    if metadata
+
+      data = @http.post("/revenue/adjustments", body)
+      Adjustment.from_hash(data)
+    end
+  end
+end

data/lib/billingio/resources/customers.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Provides access to customer management endpoints.
+  #
+  #   client.customers.create(email: "user@example.com")
+  #   client.customers.list
+  #   client.customers.get("cus_abc123")
+  #   client.customers.update("cus_abc123", name: "Jane Doe")
+  class Customers
+    # @api private
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    # Create a new customer.
+    #
+    # @param email    [String, nil]  customer email address
+    # @param name     [String, nil]  customer display name
+    # @param metadata [Hash, nil]    arbitrary key-value pairs
+    # @return [BillingIO::Customer]
+    # @raise [BillingIO::Error]
+    def create(email: nil, name: nil, metadata: nil)
+      body = {}
+      body["email"]    = email    if email
+      body["name"]     = name     if name
+      body["metadata"] = metadata if metadata
+
+      data = @http.post("/customers", body)
+      Customer.from_hash(data)
+    end
+
+    # List customers with cursor-based pagination.
+    #
+    # @param cursor [String, nil] opaque cursor for the next page
+    # @param limit  [Integer]     items per page (1..100, default 25)
+    # @return [BillingIO::PaginatedList<BillingIO::Customer>]
+    # @raise [BillingIO::Error]
+    def list(cursor: nil, limit: 25)
+      params = { limit: limit }
+      params[:cursor] = cursor if cursor
+
+      data = @http.get("/customers", params)
+      PaginatedList.from_hash(data, Customer)
+    end
+
+    # Retrieve a single customer by ID.
+    #
+    # @param customer_id [String] customer identifier (prefixed +cus_+)
+    # @return [BillingIO::Customer]
+    # @raise [BillingIO::Error]
+    def get(customer_id)
+      data = @http.get("/customers/#{customer_id}")
+      Customer.from_hash(data)
+    end
+
+    # Update an existing customer.
+    #
+    # @param customer_id [String]      customer identifier (prefixed +cus_+)
+    # @param email       [String, nil] new email address
+    # @param name        [String, nil] new display name
+    # @param metadata    [Hash, nil]   new metadata (replaces existing)
+    # @return [BillingIO::Customer]
+    # @raise [BillingIO::Error]
+    def update(customer_id, email: nil, name: nil, metadata: nil)
+      body = {}
+      body["email"]    = email    if email
+      body["name"]     = name     if name
+      body["metadata"] = metadata if metadata
+
+      data = @http.patch("/customers/#{customer_id}", body)
+      Customer.from_hash(data)
+    end
+  end
+end

data/lib/billingio/resources/entitlements.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Provides access to subscription entitlement endpoints.
+  #
+  #   client.entitlements.list(subscription_id: "sub_abc123")
+  #   client.entitlements.create(subscription_id: "sub_abc123", feature_key: "api_calls")
+  #   client.entitlements.update("ent_abc123", value: 1000)
+  #   client.entitlements.delete("ent_abc123")
+  #   client.entitlements.check(customer_id: "cus_abc123", feature_key: "api_calls")
+  class Entitlements
+    # @api private
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    # List entitlements with cursor-based pagination.
+    #
+    # @param cursor          [String, nil] opaque cursor for the next page
+    # @param limit           [Integer]     items per page (1..100, default 25)
+    # @param subscription_id [String, nil] filter by subscription
+    # @return [BillingIO::PaginatedList<BillingIO::Entitlement>]
+    # @raise [BillingIO::Error]
+    def list(cursor: nil, limit: 25, subscription_id: nil)
+      params = { limit: limit }
+      params[:cursor]          = cursor          if cursor
+      params[:subscription_id] = subscription_id if subscription_id
+
+      data = @http.get("/subscriptions/entitlements", params)
+      PaginatedList.from_hash(data, Entitlement)
+    end
+
+    # Create a new entitlement.
+    #
+    # @param subscription_id [String]       parent subscription
+    # @param feature_key     [String]       machine-readable feature identifier
+    # @param value           [Object, nil]  entitlement value
+    # @param metadata        [Hash, nil]    arbitrary key-value pairs
+    # @return [BillingIO::Entitlement]
+    # @raise [BillingIO::Error]
+    def create(subscription_id:, feature_key:, value: nil, metadata: nil)
+      body = {
+        "subscription_id" => subscription_id,
+        "feature_key"     => feature_key
+      }
+      body["value"]    = value    unless value.nil?
+      body["metadata"] = metadata if metadata
+
+      data = @http.post("/subscriptions/entitlements", body)
+      Entitlement.from_hash(data)
+    end
+
+    # Update an existing entitlement.
+    #
+    # @param entitlement_id [String]       entitlement identifier (prefixed +ent_+)
+    # @param value          [Object, nil]  new entitlement value
+    # @param metadata       [Hash, nil]    new metadata (replaces existing)
+    # @return [BillingIO::Entitlement]
+    # @raise [BillingIO::Error]
+    def update(entitlement_id, value: nil, metadata: nil)
+      body = {}
+      body["value"]    = value    unless value.nil?
+      body["metadata"] = metadata if metadata
+
+      data = @http.patch("/subscriptions/entitlements/#{entitlement_id}", body)
+      Entitlement.from_hash(data)
+    end
+
+    # Delete an entitlement.
+    #
+    # @param entitlement_id [String] entitlement identifier (prefixed +ent_+)
+    # @return [nil]
+    # @raise [BillingIO::Error]
+    def delete(entitlement_id)
+      @http.delete("/subscriptions/entitlements/#{entitlement_id}")
+      nil
+    end
+
+    # Check whether a customer has a specific entitlement.
+    #
+    # @param customer_id [String] customer identifier
+    # @param feature_key [String] feature key to check
+    # @return [BillingIO::EntitlementCheck]
+    # @raise [BillingIO::Error]
+    def check(customer_id:, feature_key:)
+      params = {
+        customer_id: customer_id,
+        feature_key: feature_key
+      }
+
+      data = @http.get("/subscriptions/entitlements/check", params)
+      EntitlementCheck.from_hash(data)
+    end
+  end
+end

data/lib/billingio/resources/payment_links.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Provides access to payment link endpoints.
+  #
+  #   client.payment_links.create(amount_usd: 25.00, chain: "tron", token: "USDT")
+  #   client.payment_links.list
+  class PaymentLinks
+    # @api private
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    # Create a new payment link.
+    #
+    # @param amount_usd [Float, nil]   fixed amount in USD (nil for open-amount)
+    # @param chain      [String, nil]  blockchain network
+    # @param token      [String, nil]  stablecoin token
+    # @param metadata   [Hash, nil]    arbitrary key-value pairs
+    # @return [BillingIO::PaymentLink]
+    # @raise [BillingIO::Error]
+    def create(amount_usd: nil, chain: nil, token: nil, metadata: nil)
+      body = {}
+      body["amount_usd"] = amount_usd if amount_usd
+      body["chain"]      = chain      if chain
+      body["token"]      = token      if token
+      body["metadata"]   = metadata   if metadata
+
+      data = @http.post("/payment-links", body)
+      PaymentLink.from_hash(data)
+    end
+
+    # List payment links with cursor-based pagination.
+    #
+    # @param cursor [String, nil] opaque cursor for the next page
+    # @param limit  [Integer]     items per page (1..100, default 25)
+    # @return [BillingIO::PaginatedList<BillingIO::PaymentLink>]
+    # @raise [BillingIO::Error]
+    def list(cursor: nil, limit: 25)
+      params = { limit: limit }
+      params[:cursor] = cursor if cursor
+
+      data = @http.get("/payment-links", params)
+      PaginatedList.from_hash(data, PaymentLink)
+    end
+  end
+end

data/lib/billingio/resources/payment_methods.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Provides access to payment method management endpoints.
+  #
+  #   client.payment_methods.create(customer_id: "cus_abc123", type: "wallet")
+  #   client.payment_methods.list
+  #   client.payment_methods.update("pm_abc123", metadata: { "label" => "main" })
+  #   client.payment_methods.delete("pm_abc123")
+  #   client.payment_methods.set_default("pm_abc123")
+  class PaymentMethods
+    # @api private
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    # Register a new payment method.
+    #
+    # @param customer_id [String]      owning customer
+    # @param type        [String]      method type (e.g. "wallet")
+    # @param chain       [String, nil] blockchain network
+    # @param token       [String, nil] stablecoin token
+    # @param address     [String, nil] wallet address
+    # @param metadata    [Hash, nil]   arbitrary key-value pairs
+    # @return [BillingIO::PaymentMethod]
+    # @raise [BillingIO::Error]
+    def create(customer_id:, type:, chain: nil, token: nil, address: nil, metadata: nil)
+      body = {
+        "customer_id" => customer_id,
+        "type"        => type
+      }
+      body["chain"]    = chain    if chain
+      body["token"]    = token    if token
+      body["address"]  = address  if address
+      body["metadata"] = metadata if metadata
+
+      data = @http.post("/payment-methods", body)
+      PaymentMethod.from_hash(data)
+    end
+
+    # List payment methods with cursor-based pagination.
+    #
+    # @param cursor      [String, nil] opaque cursor for the next page
+    # @param limit       [Integer]     items per page (1..100, default 25)
+    # @param customer_id [String, nil] filter by customer
+    # @return [BillingIO::PaginatedList<BillingIO::PaymentMethod>]
+    # @raise [BillingIO::Error]
+    def list(cursor: nil, limit: 25, customer_id: nil)
+      params = { limit: limit }
+      params[:cursor]      = cursor      if cursor
+      params[:customer_id] = customer_id if customer_id
+
+      data = @http.get("/payment-methods", params)
+      PaginatedList.from_hash(data, PaymentMethod)
+    end
+
+    # Update an existing payment method.
+    #
+    # @param payment_method_id [String]    payment method identifier (prefixed +pm_+)
+    # @param metadata          [Hash, nil] new metadata (replaces existing)
+    # @return [BillingIO::PaymentMethod]
+    # @raise [BillingIO::Error]
+    def update(payment_method_id, metadata: nil)
+      body = {}
+      body["metadata"] = metadata if metadata
+
+      data = @http.patch("/payment-methods/#{payment_method_id}", body)
+      PaymentMethod.from_hash(data)
+    end
+
+    # Delete a payment method.
+    #
+    # @param payment_method_id [String] payment method identifier (prefixed +pm_+)
+    # @return [nil]
+    # @raise [BillingIO::Error]
+    def delete(payment_method_id)
+      @http.delete("/payment-methods/#{payment_method_id}")
+      nil
+    end
+
+    # Set a payment method as the customer's default.
+    #
+    # @param payment_method_id [String] payment method identifier (prefixed +pm_+)
+    # @return [BillingIO::PaymentMethod]
+    # @raise [BillingIO::Error]
+    def set_default(payment_method_id)
+      data = @http.post("/payment-methods/#{payment_method_id}/default")
+      PaymentMethod.from_hash(data)
+    end
+  end
+end