This documentation site is deprecated. The latest up-to-date API reference is available at https://reference.chargify.com.
This site will remain available for historical reference until June 1, 2017

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
  • Preview Allocations : See a preview of a proposed allocation operation

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.
  • full-price-attempt-capture: A charge is added for the full price of the component change, and we attempt to charge the credit card on file. If it fails, the charge will be accrued until the next renewal.
  • full-price-delay-capture: A charge is added for the full price of the component change, but the card is not charged until the subscription’s 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. By default, this is an integer. If decimal allocations are enabled for the component, it will be a decimal number. 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.
payment_collection_method (optional, default automatic) For subscriptions on invoice billing, when proration_upgrade_scheme is set to either prorate-attempt-capture or full-price-attempt-capture and payment_collection_method is set to invoice, a mid-period invoice will be created from any charges that are a result of the allocation change. The charge will not appear on the invoice created at the next renewal. For subscriptions on statement billing, this option is ignored.

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
payment If capture was attempted for a mid-period allocation, includes amount_in_cents, success, memo and id attributes describing the payment, or null if no card was on file.

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.By default this should be an integer. If decimal allocations are enabled for the component, it will be a decimal number. 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
payment If capture was attempted for a mid-period allocation, includes amount_in_cents, success, memo and id attributes describing the payment, or null if no card was on file.

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 multiple Allocations

JSON: Create multiple allocations successfully

Request Data (allocation.json)


{
  "proration_upgrade_scheme": "prorate-attempt-capture",
  "proration_downgrade_scheme": "prorate",
  "allocations": [
    {
      "component_id": "11",
      "quantity": "1",
      "memo": "foo"
    },
    {
      "component_id": "77",
      "quantity": "10",
      "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_preview": {
    "start_date": "2016-12-13T18:59:38Z",
    "end_date": "2017-01-07T20:29:07Z",
    "period_type": "prorated",
    "subtotal_in_cents": 7256,
    "total_tax_in_cents": 0,
    "total_discount_in_cents": 0,
    "total_in_cents": 7256,
    "existing_balance_in_cents": 40600,
    "direction": "upgrade",
    "proration_scheme": "prorate-attempt-capture",
    "line_items": [
      {
        "transaction_type": "charge",
        "kind": "quantity_based_component",
        "amount_in_cents": -1637,
        "memo": "IP Addresses: 10 to 1 unit",
        "discount_amount_in_cents": 0,
        "taxable_amount_in_cents": 0,
        "component_id": 11
      },
      {
        "transaction_type": "charge",
        "kind": "quantity_based_component",
        "amount_in_cents": 8893,
        "memo": "dollar charges: 0 to 10 dollars",
        "discount_amount_in_cents": 0,
        "taxable_amount_in_cents": 8893,
        "component_id": 77
      }
    ]
  }
}
]

Preview Allocations

Chargify offers the ability to preview a potential subscription component allocation in the middle of the current billing period. This is useful if you want users to be able to see the effect of a component operation before actually doing it.

POST /subscriptions/<sub_id>/allocations/preview

Creates a preview of the effect of adding components to a subscription.

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 allocation_preview object with the following fields:

start_date The start date of the allocation preview
end_date The end date of the allocation preview
period_type The period type for this preview. This is always ‘prorated’ for mid-period allocations.
subtotal_in_cents The subtotal for this preview.
total_tax_in_cents The total tax in cents.
total_discount_in_cents The total discount in cents.
total_in_cents The total in cents.
existing_balance_in_cents The existing balance in cents.
direction The direction of this allocation. Valid values are ‘upgrade’ or ‘downgrade’.
proration_scheme The proration scheme for this allocation.
line_items An array of line_items, each containing transaction_type, kind, amount_in_cents, memo, discount_amount_in_cents, taxable_amount_in_cents,component_id

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 component_id, or no subscription with given sub_id exists

Examples: Create Allocation Preview

JSON: Create multiple allocations preview successfully

Request Data (allocation.json)


{
  "proration_upgrade_scheme": "prorate-attempt-capture",
  "proration_downgrade_scheme": "prorate",
  "allocations": [
    {
      "component_id": "11",
      "quantity": "1",
      "memo": "foo"
    },
    {
      "component_id": "77",
      "quantity": "10",
      "memo": "bar"
    }
  ]
}

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

Response

HTTP/1.1 201 Created

{
  "allocation_preview": {
    "start_date": "2016-12-13T18:59:38Z",
    "end_date": "2017-01-07T20:29:07Z",
    "period_type": "prorated",
    "subtotal_in_cents": 7256,
    "total_tax_in_cents": 0,
    "total_discount_in_cents": 0,
    "total_in_cents": 7256,
    "existing_balance_in_cents": 40600,
    "direction": "upgrade",
    "proration_scheme": "prorate-attempt-capture",
    "line_items": [
      {
        "transaction_type": "charge",
        "kind": "quantity_based_component",
        "amount_in_cents": -1637,
        "memo": "IP Addresses: 10 to 1 unit",
        "discount_amount_in_cents": 0,
        "taxable_amount_in_cents": 0,
        "component_id": 11
      },
      {
        "transaction_type": "charge",
        "kind": "quantity_based_component",
        "amount_in_cents": 8893,
        "memo": "dollar charges: 0 to 10 dollars",
        "discount_amount_in_cents": 0,
        "taxable_amount_in_cents": 8893,
        "component_id": 77
      }
    ]
  }
}