curl --request POST \
--url https://app.saasybill.com/api/v1/subscriptions/{id}/units \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"units": 15,
"prorate": true,
"proration_behaviour": "charge_immediately",
"effective_date": "2026-10-08"
}
'{
"id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
"object": "subscription",
"customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
"customer_code": "ACME-001",
"plan": "b6c1e0a4-2f7d-4a61-8f0c-5d3e9a7b2c44",
"status": "active",
"currency": "AUD",
"interval": {
"unit": "month",
"count": 1
},
"timezone": "Australia/Sydney",
"start_date": "2026-09-30",
"renewal_date": "2026-10-30",
"end_date": null,
"units": 15,
"minimum_units": 5,
"discount_percent": "10.00",
"cancel_at_period_end": false,
"end_after_cycles": null,
"label": "Acme – Team plan",
"invoice_reference": "PO-4471",
"renewal_value": "162.0000",
"created": "2026-09-30T04:12:00.000Z",
"change": {
"units": 15,
"invoice": {
"id": "6a9b4d0e-2c37-4f15-8d8a-7e3f1c5b9a01",
"object": "invoice",
"customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
"subscription": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
"number": "INV-0043",
"reference": null,
"status": "awaiting_approval",
"currency": "AUD",
"invoice_date": "2026-09-29T14:00:00.000Z",
"due_date": "2026-10-29T13:00:00.000Z",
"subtotal": "39.1900",
"total": "43.1100",
"credit_note_amount": "0.0000",
"amount_paid": null,
"sent": false,
"xero": {
"sync_status": "synced",
"invoice_id": "f0e9d8c7-b6a5-4f43-9210-fedcba987654",
"sync_error": null
},
"lines": [
{
"id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e99",
"type": "subscription",
"name": "Team",
"description": "Team – 5 additional seats, prorated from 8 Oct 2026",
"units": 5,
"amount": "43.5500",
"discount_amount": "4.3600",
"charge_amount": "39.1900",
"effective_date": "2026-10-07T13:00:00.000Z"
}
],
"created": "2026-09-30T04:12:01.000Z"
},
"renewal_invoice": null,
"deferred_to_renewal": false,
"credit_note": null
}
}Change a subscription's units
Sets the new total. The same classification as the Update Units dialog decides what happens: charged now on an invoice, deferred to the renewal invoice, or credited.
curl --request POST \
--url https://app.saasybill.com/api/v1/subscriptions/{id}/units \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"units": 15,
"prorate": true,
"proration_behaviour": "charge_immediately",
"effective_date": "2026-10-08"
}
'{
"id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
"object": "subscription",
"customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
"customer_code": "ACME-001",
"plan": "b6c1e0a4-2f7d-4a61-8f0c-5d3e9a7b2c44",
"status": "active",
"currency": "AUD",
"interval": {
"unit": "month",
"count": 1
},
"timezone": "Australia/Sydney",
"start_date": "2026-09-30",
"renewal_date": "2026-10-30",
"end_date": null,
"units": 15,
"minimum_units": 5,
"discount_percent": "10.00",
"cancel_at_period_end": false,
"end_after_cycles": null,
"label": "Acme – Team plan",
"invoice_reference": "PO-4471",
"renewal_value": "162.0000",
"created": "2026-09-30T04:12:00.000Z",
"change": {
"units": 15,
"invoice": {
"id": "6a9b4d0e-2c37-4f15-8d8a-7e3f1c5b9a01",
"object": "invoice",
"customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
"subscription": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
"number": "INV-0043",
"reference": null,
"status": "awaiting_approval",
"currency": "AUD",
"invoice_date": "2026-09-29T14:00:00.000Z",
"due_date": "2026-10-29T13:00:00.000Z",
"subtotal": "39.1900",
"total": "43.1100",
"credit_note_amount": "0.0000",
"amount_paid": null,
"sent": false,
"xero": {
"sync_status": "synced",
"invoice_id": "f0e9d8c7-b6a5-4f43-9210-fedcba987654",
"sync_error": null
},
"lines": [
{
"id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e99",
"type": "subscription",
"name": "Team",
"description": "Team – 5 additional seats, prorated from 8 Oct 2026",
"units": 5,
"amount": "43.5500",
"discount_amount": "4.3600",
"charge_amount": "39.1900",
"effective_date": "2026-10-07T13:00:00.000Z"
}
],
"created": "2026-09-30T04:12:01.000Z"
},
"renewal_invoice": null,
"deferred_to_renewal": false,
"credit_note": null
}
}subscriptions:write scope. See Authentication.Authorizations
An API key. Its scopes decide what it may call: customers:read (List and look up customers.) customers:write (Create customers, and Xero contacts where the organisation allows it.) catalogue:read (List plans and charges.) subscriptions:read (List and look up subscriptions.) subscriptions:write (Create subscriptions, change units, end and restore them.) invoices:read (List and look up invoices.)
Headers
1 to 255 printable characters. A retry with the same key and body returns the first response.
1 - 255"signup_8f3a2c1d"
Path Parameters
The Saasybill id of the subscription.
"9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33"
Body
The new total number of units, not a change.
0 <= x <= 999999999Charge or credit for the rest of the period. Default false.
charge_immediately, charge_on_renewal Required to prorate.
^\d{4}-\d{2}-\d{2}$Required exactly when the next period has already been invoiced (inside the invoice window): amend the renewal invoice, or bill the change on its own. Refused otherwise. The error names the choices.
amend, separate Response
Success.
"subscription"pending, active, complete, ended Show child attributes
Show child attributes
YYYY-MM-DD, in the subscription's own timezone.
YYYY-MM-DD, in the subscription's own timezone.
YYYY-MM-DD, in the subscription's own timezone.
A decimal string, e.g. "19.9900".
A decimal string, e.g. "19.9900".
ISO 8601, UTC.
Show child attributes
Show child attributes
Was this page helpful?