Allocate Components
Creates multiple allocations, sets the current allocated quantity for each of the components, and records a memo. A component_id is required for each allocation.
The charges and/or credits that are created will be rolled up into a single total which is used to determine whether this is an upgrade or a downgrade.
Order of Resolution for upgrade_charge and downgrade_credit
- Per allocation in API call (within a single allocation of the
allocationsarray) - Component-level default value
- Allocation API call top level (outside of the
allocationsarray) - Site-level default value
Order of Resolution for accrue charge
- Allocation API call top level (outside of the
allocationsarray) - Site-level default value
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.
For more information, see the Component Allocations product documentation.
Authorization
BasicAuth The username is a Maxio Chargify API key. The password is x.
In: header
Path Parameters
The Chargify id of the subscription.
Request Body
application/json
The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided.
Value in
- "full"
- "prorated"
- "none"
- null
The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided.
Value in
- "full"
- "prorated"
- "none"
- null
(Optional) If not passed, the allocation(s) will use the payment collection method on the subscription.
Value in
- "automatic"
- "remittance"
- "prepaid"
- "invoice"
If true, if the immediate component payment fails, initiate dunning for the subscription. Otherwise, leave the charges on the subscription to pay for at renewal.
Response Body
application/json
application/json
curl -X POST "https://example.com/subscriptions/0/allocations.json" \ -H "Content-Type: application/json" \ -d '{ "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" } ] }'[ { "allocation": { "component_id": 193159, "subscription_id": 15540611, "quantity": 10, "previous_quantity": 0, "memo": "foo", "timestamp": "2016-12-08T19:09:15Z", "proration_upgrade_scheme": "prorate-attempt-capture", "proration_downgrade_scheme": "no-prorate", "payment": { "amount_in_cents": 1451, "success": true, "memo": "Payment for: Prorated component allocation changes.", "id": 165473487 } } }, { "allocation": { "component_id": 277221, "subscription_id": 15540611, "quantity": 5, "previous_quantity": 0, "memo": "bar", "timestamp": "2016-12-08T19:09:15Z", "proration_upgrade_scheme": "prorate-attempt-capture", "proration_downgrade_scheme": "no-prorate", "payment": { "amount_in_cents": 1451, "success": true, "memo": "Payment for: Prorated component allocation changes.", "id": 165473487 } } }]Allocate Component POST
Creates an allocation, sets the current allocated quantity for the component, and records a memo. Allocations can only be updated for Quantity, On/Off, and Prepaid Components. When creating an allocation via the API, you can pass the `upgrade_charge`, `downgrade_credit`, and `accrue_charge` to be applied. > **Note:** These proration and accrual fields are ignored for Prepaid Components since this component type always generates charges immediately without proration. For information on prorated components and upgrade/downgrade schemes, see [Setting Component Allocations.](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Component-Allocations-Proration) ### Order of Resolution for upgrade_charge and downgrade_credit 1. Per allocation in API call (within a single allocation of the `allocations` array) 2. [Component-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Component-Allocations-Overview) 3. Allocation API call top level (outside of the `allocations` array) 4. [Site-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Component-Allocations-Proration#proration-schemes) ### Order of Resolution for accrue charge 1. Allocation API call top level (outside of the `allocations` array) 2. [Site-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Component-Allocations-Proration#proration-schemes) > **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. For more information, see the [Component Allocations](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Component-Allocations-Overview) product Documentation.
Preview Allocations POST
Previews a potential subscription's **quantity-based** or **on/off** 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. ## Fine-grained Component Control: Use with multiple `upgrade_charge`s or `downgrade_credits` When the allocation uses multiple different types of `upgrade_charge`s or `downgrade_credit`s, the Allocation is viewed as an Allocation which uses "Fine-Grained Component Control". As a result, the response will not include `direction` and `proration` within the `allocation_preview`, but at the `line_items` and `allocations` level respectfully. See example below for Fine-Grained Component Control response.