API: Quantity Component Allocations

The “Allocated Quantity” may be set for the Quantity Component on specific subscriptions via the API at the time the subscription is created, or at any time thereafter.

Setting the Quantity at Subscription Creation

You may set the quantity when you create the subscription by including some extra data in your POST request. The subscription creation URL is:

https://[subdomain].chargify.com/subscriptions.[format]

In addition to the normal post data, also include a ‘components’ attribute, as follows:

JSON Data

{
  "subscription": {
    ...normal subscription attributes...
    "components":[
      {
        "component_id": 1,
        "allocated_quantity": 18
      }
    ]
  }
}

XML Data

<?xml version="1.0" encoding="UTF-8"?>
<subscription>
  ...normal subscription attributes...
  <components type="array">
    <component>
      <component_id>1</component_id>
      <allocated_quantity>14</allocated_quantity>
    </component>
  </components>
</subscription>

Via the official Chargify Gem

Chargify::Subscription.create(
  :product_id => 2,
  :customer_id => 1,
  :credit_card_attributes => {
    :full_number => 1,
    :first_name => "John",
    :last_name => "Doe",
    :expiration_month => "2",
    :expiration_year => "2020"
  },
  :components => [
    {
      :component_id => 1,
      :allocated_quantity => 15
    }
  ]
)

Updating the Quantity

After a subscription has been created, you may set or update the quantity at any time by sending a PUT request with component data to the following URL:

 https://[subdomain].chargify.com/subscriptions/[subscription_id]/components/[component_id].[format]

JSON Data:

{
  "component": {
    "allocated_quantity":23
  }
}

XML Data:

<component>
  <allocated_quantity type="integer">23</allocated_quantity>
</component>

Via the official Chargify Gem

# First way to find and update a component
component = Chargify::Subscription::Component.find(1, :params => {:subscription_id => 2})
component.allocated_quantity = 23
component.save

# Second way to find and update a component
subscription = Chargify::Subscription.find(2)
component = subscription.component(1)
component.allocated_quantity = 23
component.save

subscription = Chargify::Subscription.find(2)
subscription.component(1).allocated_quantity = 
Chargify::Subscription.create(
  :product_id => 2,
  :customer_id => 1,
  :credit_card_attributes => {
    :full_number => 1,
    :first_name => "John",
    :last_name => "Doe",
    :expiration_month => "2",
    :expiration_year => "2020"
  },
  :components => [
    {
      :component_id => 1,
      :allocated_quantity => 15
    }
  ]
)

Reading Current Quantity

You can query the API to receive the current quantity for a Quantity Component by sending a GET request to the following URL:

https://<subdomain>.chargify.com/subscriptions/<subscription_id>/components/<component_id>.<format>

You’ll receive data like the following:

JSON Data

{
  "component": {
    "name":"Paying Customers",
    "kind":"quantity_based_component",
    "subscription_id":"7",
    "component_id":"1",
    "allocated_quantity":23,
    "pricing_scheme":"stairstep",
    "unit_name":"customers"
  }
}

XML Data

<?xml version="1.0" encoding="UTF-8"?>
<component>
  <allocated_quantity type="integer">23</allocated_quantity>
  <component_id>1</component_id>
  <subscription_id>7</subscription_id>
  <name>Paying Customers</name>
  <unit_name>customers</unit_name>
  <kind>quantity_based_component</kind>
  <pricing_scheme>stairstep</pricing_scheme>
</component>

You can also query the current quantity via the official Chargify Gem:

# First way
component = Chargify::Subscription::Component.find(1, :params => {:subscription_id => 7})
puts component.allocated_quantity
# => 23

# Second way
component = Chargify::Subscription.find(7).component(1)
puts component.allocated_quantity
# => 23