Bulk Update Subscription Items

POST

/api/:account_id/subscriptions/bulk-update-items

POST

/api/:account_id/subscriptions/bulk-update-items

$ curl -X POST https://app.paymentkit.com/api/account_id/subscriptions/bulk-update-items \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "subscriptions": [
>     {
>       "subscription_id": "sub_8f3a2b7c9d1e4f6a",
>       "items": [
>         {},
>         {},
>         {}
>       ]
>     },
>     {
>       "subscription_id": "sub_4d2c1e9b7a6f3c8d",
>       "items": [
>         {}
>       ]
>     }
>   ]
> }'

1 {
2   "total_processed": 2,
3   "total_succeeded": 1,
4   "total_failed": 1,
5   "total_proration_amount_atom": 1500,
6   "invoices_created": 1,
7   "floating_items_created": 2,
8   "succeeded": [
9     {
10       "subscription_id": "sub_8f3a2b7c9d1e4f6a",
11       "proration_amount_atom": 1500,
12       "invoice_id": "inv_20240615_001",
13       "floating_items_created": 2
14     }
15   ],
16   "failed": [
17     {
18       "subscription_id": "sub_4d2c1e9b7a6f3c8d",
19       "error_code": "subscription_not_found",
20       "error_message": "Subscription ID sub_4d2c1e9b7a6f3c8d does not exist or belongs to another account."
21     }
22   ]
23 }

Bulk update subscription items across multiple subscriptions.

Updates items on up to 100 subscriptions in a single API call. Returns HTTP 200 even for partial failures - check the failed list.

Supports PAUSED subscriptions (in addition to ACTIVE, TRIALING, PAST_DUE). Proration is automatically skipped for PAUSED and TRIALING subscriptions.

Each subscription is processed independently - one failure doesn’t affect others.

Supported item operations (same as single update):

Add new item: {"price_id": "price_xxx", "quantity": 2}
Update existing item: {"id": "si_xxx", "quantity": 5}
Delete item: {"id": "si_xxx", "deleted": true}
Schedule removal: {"id": "si_xxx", "drop_at_end": true}

Error codes for failed subscriptions:

subscription_not_found: Subscription doesn’t exist or belongs to another account
invalid_state: Subscription in CANCELLED, INCOMPLETE, or SCHEDULED state
interval_mismatch: Price interval doesn’t match subscription interval
validation_error: Invalid item change
payment_failed: Payment failed (for always_invoice behavior)

Bulk update subscription items across multiple subscriptions. Updates items on up to 100 subscriptions in a single API call. Returns HTTP 200 even for partial failures - check the failed list. Supports PAUSED subscriptions (in addition to ACTIVE, TRIALING, PAST_DUE). Proration is automatically skipped for PAUSED and TRIALING subscriptions. Each subscription is processed independently - one failure doesn't affect others. **Supported item operations** (same as single update): - Add new item: `{"price_id": "price_xxx", "quantity": 2}` - Update existing item: `{"id": "si_xxx", "quantity": 5}` - Delete item: `{"id": "si_xxx", "deleted": true}` - Schedule removal: `{"id": "si_xxx", "drop_at_end": true}` **Error codes for failed subscriptions:** - `subscription_not_found`: Subscription doesn't exist or belongs to another account - `invalid_state`: Subscription in CANCELLED, INCOMPLETE, or SCHEDULED state - `interval_mismatch`: Price interval doesn't match subscription interval - `validation_error`: Invalid item change - `payment_failed`: Payment failed (for always_invoice behavior)

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Request

This endpoint expects an object.

subscriptionslist of objectsRequired

proration_behaviorenumOptional

Proration behavior for mid-cycle subscription changes.

ALWAYS_INVOICE: Create invoice immediately and attempt payment now
CREATE_PRORATIONS: Create floating items (invoice_id=NULL) for next renewal
NONE: No proration, changes apply at next renewal only

Response

Successful Response

total_processedinteger

total_succeededinteger

total_failedinteger

total_proration_amount_atominteger

invoices_createdinteger

floating_items_createdinteger

succeededlist of objectsOptional

failedlist of objectsOptional

Errors

422

Unprocessable Entity Error