Skip to main content
POST
/
api
/
v1
/
subscriptions
/
bulk-assign-plans
cURL
curl -X POST https://api.metrifox.com/api/v1/subscriptions/bulk-assign-plans \
  -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",
    "skip_invoice": false
  }'
{
  "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.

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
required

The billing interval for the subscription. Must be an interval available on the plan.

Example:

"monthly"

​
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.

Response

Bulk assignment completed (may include partial failures)

​
statusCode
integer
Example:

200

​
message
string
Example:

"Bulk plan assignment completed"

​
data
object
​
errors
object