Skip to main content
POST
/
api
/
v1
/
subscriptions
/
bulk-assign-plan
cURL
curl -X POST https://api.metrifox.com/api/v1/subscriptions/bulk-assign-plan \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_keys": ["cust_001", "cust_002", "cust_003"],
    "plan_key": "pro-plan",
    "billing_interval": "monthly",
    "currency_code": "EUR",
    "skip_invoice": true,
    "start_date": "2026-04-01"
  }'
{ "statusCode": 200, "message": "Bulk plan assignment completed", "meta": {}, "data": { "succeeded": [ { "customer_key": "cust_001" }, { "customer_key": "cust_002" } ], "failed": [] }, "errors": {} }
Each customer is processed independently. If some customers fail (e.g., customer not found, already subscribed), the others will still be assigned. Check both succeeded and failed arrays in the response.
Use skip_invoice: true when migrating customers who have already paid outside of Metrifox. The subscription and order will be created, but no invoice will be generated.
billing_interval is optional for free plans. You can omit it and the subscription will be created without a billing cycle. For paid plans, billing_interval is required and must match one of the intervals configured on the plan.
Use currency_code when your plan has localized pricing in multiple currencies and you want to pin the subscription to a specific currency (e.g. "EUR" for a European customer). If omitted, the plan’s default product currency is used.
Use start_date to backdate subscriptions when onboarding was delayed. Pass a date string in the past (e.g. "2026-04-01") and the subscription will be created with that start date. Combine with skip_invoice: true to avoid charging for the gap period. Future dates are not allowed.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
customer_keys
string[]
required

Array of customer keys to assign to the plan

Example:
["cust_001", "cust_002", "cust_003"]
​
plan_key
string
required

The offering key of the plan to assign

Example:

"pro-plan"

​
billing_interval
string

The billing interval for the subscription. Must be an interval available on the plan. Required for paid plans. Can be omitted when assigning a free plan.

Example:

"monthly"

​
currency_code
string

The ISO 4217 currency code to use when selecting the plan's price option. Use this when your plan has localized pricing in multiple currencies and you want to assign a specific currency to the customer. If omitted, the plan's default product currency is used.

Example:

"EUR"

​
items
object[]

Optional entitlement or credit items to include with the subscription. Each item must have either a feature_key or credit_key, plus a quantity.

​
skip_invoice
boolean
default:false

When true, subscriptions are created without generating invoices. Use this for customer migrations where payment has already been collected externally.

​
start_date
string<date>

A date string in the past to backdate the subscription start (e.g. "2026-04-01"). Use this when onboarding was delayed and you want the subscription to reflect the original agreed-upon start date. Must be in the past — future dates are rejected. If omitted, the subscription starts immediately.

Example:

"2026-04-01"

Response

Bulk assignment completed (may include partial failures)

​
statusCode
integer
Example:

200

​
message
string
Example:

"Bulk plan assignment completed"

​
data
object
​
errors
object