API: Allocations

Allocations describe a change to the allocated quantity for a particular Component (either Quantity-Based or On/Off) for a particular Subscription.

Working with this resource, you can:

  • List Allocations : View the history of the allocated quantity for the component over time
  • Create an Allocation : Set a new allocated quantity for the line-item (as an alternative to setting the allocated quantity directly on the Component Line-Item resource)
  • Create multiple Allocations : Change the allocated quantity of multiple components at once

Proration Schemes

Changing the allocated quantity of a component mid-period can result in either a prorated charge or adjustment being applied to the subscription. When creating an allocation via the API, you can pass the proration_upgrade_scheme and the proration_downgrade_scheme to be applied.

For background information on prorated components and upgrade/downgrade schemes, see: API: Setting Component Allocations

The available ‘upgrade’ schemes are:

  • prorate-delay-capture: A charge is added for the prorated amount due, but the card is not charged until the subscription’s next renewal
  • prorate-attempt-capture: A charge is added and we attempt to charge the credit card on file. If it fails, the charge will be accrued until the next renewal.
  • no-prorate: No charge is added.

The available ‘downgrade’ schemes are:

  • prorate: A credit is added for the amount owed.
  • no-prorate: No credit is added

NOTE: Proration uses the current price of the component as well as the current tax rates. Changes to either may cause the prorated charge/credit to be wrong.

List Allocations

GET /subscriptions/<sub_id>/components/<comp_id>/allocations

Returns the 50 most recent Allocations, ordered by most recent first.

Input Parameters

page (optional) Pass an integer in the page parameter via the query string to access subsequent pages of 50 transactions

Output

An array of allocation objects with the following fields:

component_id The integer component ID for the allocation. This references a component that you have created in your Product setup
subscription_id The integer subscription ID for the allocation. This references a unique subscription in your Site
quantity The allocated quantity set in to effect by the allocation
previous_quantity The allocated quantity that was in effect before this allocation was created
memo The memo passed when the allocation was created
timestamp The time that the allocation was recorded, in ISO 8601 format and UTC timezone, i.e. 2012-11-20T22:00:37Z
proration_upgrade_scheme The scheme used if the proration was an upgrade. This is only present when the allocation was created mid-period.
proration_downgrade_scheme The scheme used if the proration was a downgrade. This is only present when the allocation was created mid-period.

Response Status Codes

200 OK OK: Response returned
401 Unauthorized Authentication credentials were incorrect
404 Not Found Either no component with the given comp_id, or no subscription with given sub_id exists

Create an Allocation

POST /subscriptions/<sub_id>/components/<comp_id>/allocations

Creates a new Allocation, setting the current allocated quantity for the component and recording a memo.

Input Fields

quantity The allocated quantity to which to set the line-items allocated quantity. This should always be an integer. For On/Off components, use 1 for on and 0 for off.
memo (optional) A memo to record along with the allocation
proration_upgrade_scheme (optional) The scheme used if the proration is an upgrade. Defaults to the site setting if one is not provided.
proration_downgrade_scheme (optional) The scheme used if the proration is a downgrade. Defaults to the site setting if one is not provided.

Output

An allocation object with the following fields:

component_id The integer component ID for the allocation. This references a component that you have created in your Product setup
subscription_id The integer subscription ID for the allocation. This references a unique subscription in your Site
quantity The allocated quantity set in to effect by the allocation
previous_quantity The allocated quantity that was in effect before this allocation was created
memo The memo passed when the allocation was created
proration_upgrade_scheme The scheme used if the proration was an upgrade. This is only present when the allocation was created mid-period.
proration_downgrade_scheme The scheme used if the proration was a downgrade. This is only present when the allocation was created mid-period.
timestamp The time that the allocation was recorded, in ISO 8601 format and UTC timezone, i.e. 2012-11-20T22:00:37Z

Response Status Codes

201 Created Allocation created successfully
422 Unprocessable Entity Invalid inputs provided: inspect the errors in the response for details
401 Unauthorized Authentication credentials were incorrect
404 Not Found Either no component with the given comp_id, or no subscription with given sub_id exists

Create multiple Allocations (JSON only)

POST /subscriptions/<sub_id>/allocations

Creates multiple Allocations, setting the current allocated quantity for each the component and recording a memo. If a proration scheme is provided, the charges that are created will be rolled up into a single payment.

Input Fields

allocations An array of allocations, each containing a component_id, quantity, and memo
proration_upgrade_scheme (optional) The scheme used if the proration is an upgrade. Defaults to the site setting if one is not provided.
proration_downgrade_scheme (optional) The scheme used if the proration is a downgrade. Defaults to the site setting if one is not provided.

Output

An array of allocation objects with the following fields:

component_id The integer component ID for the allocation. This references a component that you have created in your Product setup
subscription_id The integer subscription ID for the allocation. This references a unique subscription in your Site
quantity The allocated quantity set in to effect by the allocation. This should always be an integer. For On/Off components, use 1 for on and 0 for off.
previous_quantity The allocated quantity that was in effect before this allocation was created
memo The memo passed when the allocation was created
proration_upgrade_scheme The scheme used if the proration was an upgrade. This is only present when the allocation was created mid-period.
proration_downgrade_scheme The scheme used if the proration was a downgrade. This is only present when the allocation was created mid-period.
timestamp The time that the allocation was recorded, in ISO 8601 format and UTC timezone, i.e. 2012-11-20T22:00:37Z

Response Status Codes

201 Created Allocation created successfully
422 Unprocessable Entity Invalid inputs provided: inspect the errors in the response for details
401 Unauthorized Authentication credentials were incorrect
404 Not Found Either no component with the given comp_id, or no subscription with given sub_id exists

Examples: List Allocations

JSON: Fetch first page (up to 50) of allocations

Response is an array, ordered most recent first.

Request

curl -u <api_key>:X https://<subdomain>.chargify.com/subscriptions/2585595/components/11960/allocations.json

Response

[
  {
    "allocation":{
      "memo":"moving to 7",
      "timestamp":"2012-11-20T22:00:37Z",
      "quantity":7,
      "previous_quantity":3,
      "component_id":11960,
      "subscription_id":2585595,
      "proration_upgrade_scheme":"no-prorate",
      "proration_downgrade_scheme":"no-prorate"
    }
  },
  {
    "allocation":{
      "memo":null,
      "timestamp":"2012-11-20T21:48:09Z",
      "quantity":3,
      "previous_quantity":0,
      "component_id":11960,
      "subscription_id":2585595,
      "proration_upgrade_scheme":"no-prorate",
      "proration_downgrade_scheme":"no-prorate"
    }
  }
]

XML: Fetch first page (up to 50) of allocations

Response is an array, ordered most recent first.

Request

curl -u <api_key>:X https://<subdomain>.chargify.com/subscriptions/2585595/components/11960/allocations.xml

Response

<?xml version="1.0" encoding="UTF-8"?>
<allocations type="array">
  <allocation>
    <timestamp>2012-11-20T22:00:37Z</timestamp>
    <quantity type="integer">7</quantity>
    <previous_quantity type="integer">3</previous_quantity>
    <component_id type="integer">11960</component_id>
    <memo>moving to 7</memo>
    <subscription_id type="integer">2585595</subscription_id>
  </allocation>
  <allocation>
    <timestamp>2012-11-20T21:48:09Z</timestamp>
    <quantity type="integer">3</quantity>
    <previous_quantity type="integer">0</previous_quantity>
    <component_id type="integer">11960</component_id>
    <memo nil="true"></memo>
    <subscription_id type="integer">2585595</subscription_id>
  </allocation>
</allocations>

JSON: Fetch second page (up to 50 more) of allocations

Response is an array, ordered most recent first. In this example, there are no results in page 2 (response is an empty array) indicating that all allocations for this component and subscription have already been fetched.

Request

curl -u <api_key>:X https://<subdomain>.chargify.com/subscriptions/2585595/components/11960/allocations.json

Response

[]

XML: Fetch second page (up to 50 more) of allocations

Response is an array, ordered most recent first. In this example, there are no results in page 2 (response is an empty array) indicating that all allocations for this component and subscription have already been fetched.

Request

curl -u <api_key>:X https://<subdomain>.chargify.com/subscriptions/2585595/components/11960/allocations.xml

Response

<?xml version="1.0" encoding="UTF-8"?>
<allocations type="array"/>

Examples: Create an Allocation

JSON: Create an Allocation successfully

Request Data (allocation.json)

{
  "allocation":{
    "proration_upgrade_scheme": "prorate-attempt-capture",
    "proration_downgrade_scheme": "no-prorate",
    "quantity":2,
    "memo":"Setting quantity to 2 at customer request"
  }
}

Request

curl -u <api_key>:X -H "Content-Type:application/json" --data allocation.json https://acme.chargify.com/subscriptions/2585595/components/11960/allocations.json

Response

HTTP/1.1 201 Created
{
  "allocation":{
    "component_id":11960,
    "subscription_id":2585595,
    "quantity":2,
    "previous_quantity":18,
    "memo":"Setting quantity to 2 at customer request",
    "timestamp":"2012-11-20T23:00:08Z",
    "proration_upgrade_scheme":"prorate-attempt-capture",
    "proration_downgrade_scheme":"no-prorate"
  }
}

JSON: Attempting to create an Allocation with faulty input data

Request Data (allocation.json)

{
  "allocation":{
    "memo":"I did not specify a quantity!"
  }
}

Request

curl -u <api_key>:X -H "Content-Type:application/json" --data allocation.json https://acme.chargify.com/subscriptions/2585595/components/11960/allocations.json

Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors":["Quantity: cannot be blank."]
}

JSON: Create multiple Allocations successfully

Request Data (allocation.json)

{
  "allocation":{
    "quantity":2,
    "memo":"Setting quantity to 2 at customer request"
  }
}

Request

curl -u <api_key>:X -H "Content-Type:application/json" --data allocation.json https://acme.chargify.com/subscriptions/2585595/components/11960/allocations.json

Response

HTTP/1.1 201 Created
{
  "allocation":{
    "component_id":11960,
    "subscription_id":2585595,
    "quantity":2,
    "previous_quantity":18,
    "memo":"Setting quantity to 2 at customer request",
    "timestamp":"2012-11-20T23:00:08Z",
    "proration_upgrade_scheme":"no-prorate",
    "proration_downgrade_scheme":"no-prorate"
  }
}

Examples: Create multiples Allocations

JSON: Create multiple allocations successfully

Request Data (allocation.json)


  {
    "proration_upgrade_scheme": "prorate-attempt-capture",
    "proration_downgrade_scheme": "no-prorate",
    "allocations": [
      { "component_id": 123, "quantity": 10, "memo": "foo" },
      { "component_id": 456, "quantity": 5, "memo": "bar" },
    ]
  }

Request
curl -u <api_key>:X -H "Content-Type:application/json" --data allocation.json https://acme.chargify.com/subscriptions/2585595/allocations.json

Response

HTTP/1.1 201 Created
[
  {
    "allocation":{
      "memo":"foo",
      "timestamp":"2012-11-20T22:00:37Z",
      "quantity":10,
      "previous_quantity":3,
      "component_id":123,
      "subscription_id":2585595,
      "proration_upgrade_scheme":"no-prorate",
      "proration_downgrade_scheme":"no-prorate"
    }
  },
  {
    "allocation":{
      "memo":"bar",
      "timestamp":"2012-11-20T21:48:09Z",
      "quantity":5,
      "previous_quantity":0,
      "component_id":456,
      "subscription_id":2585595,
      "proration_upgrade_scheme":"no-prorate",
      "proration_downgrade_scheme":"no-prorate"
    }
  }
]