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)

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

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
memo (optional) A memo to record along with the allocation

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 (Note: this value is only available in the response from the Allocation creation – it is not available later when listing allocations)
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

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,
      "component_id":11960,
      "subscription_id":2585595
    }
  },
  {
    "allocation":{
      "memo":null,
      "timestamp":"2012-11-20T21:48:09Z",
      "quantity":3,
      "component_id":11960,
      "subscription_id":2585595
    }
  }
]

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>
    <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>
    <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":{
    "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"
  }
}

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."]
}