Maxio Advanced Billing
HomeSDKsAPI ReferenceContext Plugin
Subscription Components

Preview Allocations

POST
/subscriptions/{subscription_id}/allocations/preview.json

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_charges or downgrade_credits

When the allocation uses multiple different types of upgrade_charges or downgrade_credits, 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.

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.

Request Body

application/json

allocations*array<>
effective_proration_date?string

To calculate proration amounts for a future time. Only within a current subscription period. Only ISO8601 format is supported.

Formatdate
upgrade_charge?|

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

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

Response Body

application/json

application/json

curl -X POST "https://example.com/subscriptions/0/allocations/preview.json" \  -H "Content-Type: application/json" \  -d '{    "allocations": [      {        "proration_upgrade_scheme": "prorate-attempt-capture",        "proration_downgrade_scheme": "prorate",        "component_id": 554108,        "price_point_id": 325826,        "quantity": 10,        "memo": "NOW"      }    ],    "effective_proration_date": "2023-11-01"  }'
{  "allocation_preview": {    "start_date": "2019-05-02T15:26:46Z",    "end_date": "2019-05-08T15:26:46Z",    "period_type": "prorated",    "total_in_cents": 150,    "total_discount_in_cents": 0,    "total_tax_in_cents": 0,    "subtotal_in_cents": 150,    "existing_balance_in_cents": 0,    "accrue_charge": true,    "line_items": [      {        "direction": "upgrade",        "transaction_type": "charge",        "kind": "quantity_based_component",        "amount_in_cents": 100,        "taxable_amount_in_cents": 0,        "discount_amount_in_cents": 0,        "memo": "Foo: 0 to 10 foo",        "component_id": 123,        "component_handle": "foo"      },      {        "direction": "downgrade",        "transaction_type": "credit",        "kind": "quantity_based_component",        "amount_in_cents": -20,        "taxable_amount_in_cents": 0,        "discount_amount_in_cents": 0,        "memo": "Foo: 10 to 5 bar",        "component_id": 456,        "component_handle": "bar"      },      {        "direction": "upgrade",        "transaction_type": "credit",        "kind": "quantity_based_component",        "amount_in_cents": 70,        "taxable_amount_in_cents": 0,        "discount_amount_in_cents": 0,        "memo": "Foo: 0 to 10 baz",        "component_id": 789,        "component_handle": "baz"      }    ],    "allocations": [      {        "accrue_charge": true,        "upgrade_charge": "prorated",        "downgrade_credit": "full",        "component_handle": "foo",        "component_id": 123,        "memo": "foo",        "previous_price_point_id": 123,        "previous_quantity": 0,        "price_point_id": 123,        "proration_downgrade_scheme": "full",        "proration_upgrade_scheme": "prorate-delay-capture",        "quantity": 10,        "subscription_id": 123456,        "timestamp": null      },      {        "accrue_charge": true,        "upgrade_charge": "full",        "downgrade_credit": "prorated",        "component_handle": "bar",        "component_id": 456,        "memo": "foo",        "previous_price_point_id": 456,        "previous_quantity": 10,        "price_point_id": 456,        "proration_downgrade_scheme": "prorate",        "proration_upgrade_scheme": "full-price-delay-capture",        "quantity": 5,        "subscription_id": 123456,        "timestamp": null      },      {        "accrue_charge": true,        "upgrade_charge": "full",        "downgrade_credit": "none",        "component_handle": "baz",        "component_id": 789,        "memo": "foo",        "previous_price_point_id": 789,        "previous_quantity": 0,        "price_point_id": 789,        "proration_downgrade_scheme": "no-prorate",        "proration_upgrade_scheme": "full-price-delay-capture",        "quantity": 10,        "subscription_id": 123456,        "timestamp": null      }    ]  }}

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.

Delete Prepaid Usage Allocation DELETE

Deletes a prepaid usage allocation. Prepaid Usage components are unique in that their allocations are always additive. In order to reduce a subscription's allocated quantity for a prepaid usage component, each allocation must be destroyed individually via this endpoint. ## Credit Scheme By default, destroying an allocation will generate a service credit on the subscription. This behavior can be modified with the optional `credit_scheme` parameter on this endpoint. The accepted values are: 1. `none`: The allocation will be destroyed and the balances will be updated but no service credit or refund will be created. 2. `credit`: The allocation will be destroyed and the balances will be updated and a service credit will be generated. This is also the default behavior if the `credit_scheme` param is not passed. 3. `refund`: The allocation will be destroyed and the balances will be updated and a refund will be issued along with a Credit Note.