Maxio Advanced Billing
HomeSDKsAPI ReferenceContext Plugin
Subscription Components

Allocate Component

POST
/subscriptions/{subscription_id}/components/{component_id}/allocations.json

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.

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
  3. Allocation API call top level (outside of the allocations array)
  4. Site-level default value

Order of Resolution for accrue charge

  1. Allocation API call top level (outside of the allocations array)
  2. 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
AuthorizationBasic <token>

The username is a Maxio Chargify API key. The password is x.

In: header

Path Parameters

subscription_id*integer

The Chargify id of the subscription.

component_id*integer

The Advanced Billing id of the component

Request Body

application/json

allocation*

Response Body

application/json

application/json

curl -X POST "https://example.com/subscriptions/0/components/0/allocations.json" \  -H "Content-Type: application/json" \  -d '{    "allocation": {      "quantity": 10,      "decimal_quantity": "10.0",      "previous_quantity": 5,      "decimal_previous_quantity": "5.0",      "memo": "Increase seats to 10",      "proration_upgrade_scheme": "full-price-attempt-capture",      "proration_downgrade_scheme": "prorate",      "accrue_charge": false,      "upgrade_charge": "full",      "downgrade_credit": "prorated",      "price_point_id": 789,      "billing_schedule": {        "initial_billing_at": "2025-02-28"      },      "custom_price": {        "pricing_scheme": "per_unit",        "tax_included": false,        "renew_prepaid_allocation": false,        "rollover_prepaid_remainder": false,        "expiration_interval": null,        "expiration_interval_unit": "never",        "interval": 1,        "interval_unit": "month",        "list_price_point_id": 4321,        "use_default_list_price": false,        "prices": [          {            "starting_quantity": 1,            "ending_quantity": 25,            "unit_price": "49.00"          },          {            "starting_quantity": 26,            "ending_quantity": null,            "unit_price": "39.00"          }        ]      }    }  }'
{  "allocation": {    "component_id": 4034995,    "subscription_id": 23737320,    "quantity": 3,    "previous_quantity": 2,    "memo": "dolore cupidatat elit",    "timestamp": "2022-11-23T10:28:34-05:00",    "proration_upgrade_scheme": "laboris ipsum dolore",    "proration_downgrade_scheme": "eiusmod dolore",    "price_point_id": -69720370,    "previous_price_point_id": -76493052,    "accrue_charge": true,    "upgrade_charge": "full",    "downgrade_credit": "full",    "payment": {      "id": -44566528,      "amount_in_cents": 123,      "success": false,      "memo": "aliqua"    }  }}

List Allocations GET

Lists the 50 most recent Allocations, ordered by most recent first. ## On/Off Components When a subscription's on/off component has been toggled to on (`1`) or off (`0`), usage will be logged in this response.

Allocate Components POST

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