Bulk update subscription billing interval

Updates the billing interval configuration for subscription contracts in bulk.

Full behavior, validation rules, and side effects

Endpoint: PUT /api/external/v2/bulk-automations/billing-interval

Authentication:

• API Key (query parameter: api_key) Query Parameters:
• api_key (required) – Your API key
• intervalCount (required) – Billing interval frequency (e.g. 1, 2, 3)
• interval (required) – Billing interval type (DAY, WEEK, MONTH, YEAR)
• suppressEmailNotification (optional) – Suppress email notification to customer (true/false)
• allSubscriptions (optional) – Apply to all subscriptions for the shop (true/false)

Request Body:

{
  "subscriptionIds": "41982558492,41838280988"
}

What This Endpoint Does:

• Updates the billing interval (frequency + interval type) for provided subscription contracts
• Creates a bulk automation task
• Processes updates asynchronously in the background using AWS Step Functions

How It Works:

1. Merchant provides billing interval details via query parameters
2. Subscription IDs are provided as a comma-separated string in the request body (ignored if allSubscriptions=true)
3. System validates shop ownership and ensures no bulk job is currently running
4. Bulk automation job is created
5. Billing interval is updated for each subscription asynchronously

Important Notes:

• Only one bulk automation per shop can run at a time
• interval must match SellingPlanInterval enum values exactly (DAY, WEEK, MONTH, YEAR)
• Processing is asynchronous
• Previously generated orders are not modified
• If allSubscriptions=true, provided subscriptionIds will be ignored
• If allSubscriptions=false, subscriptionIds cannot be empty

PUT /api/external/v2/bulk-automations/billing-interval

Bulk update subscription billing interval

cURL

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/bulk-automations/billing-interval \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscriptionIds": "<string>"
}
'

204

{}

Query Parameters

api_key · string · required

Your API Key

intervalCount · integer<int32> · required

interval · enum<string> · required

Available options: DAY, WEEK, MONTH, YEAR, $UNKNOWN

suppressEmailNotification · boolean

allSubscriptions · boolean

Body

application/json

subscriptionIds · string

Response

204

application/json

Bulk billing interval update successfully queued and initiated.