Skip to main content
POST
cURL
Provide exactly one customer identifier: customer_id or customer_key. Do not send both. Every line item must reference a resource owned by your tenant.
Your API key must have the write or admin scope. Pass the raw key in the x-api-key header.
An order can contain at most one plan line item, and its quantity must be 1. For an invoice line item, omit price_option_id; Metrifox creates a carryover item and sets the quantity to 1.

Find the correct price option

For every priced line item, send the ID of the price option whose price.currency matches the order’s currency_code. An item can have price options in several currencies, so do not use a price option based only on the item ID. Retrieve the product and its full offering details with a read, write, or admin API key:
You can also provide country_code as a query parameter when you want the response filtered to the product’s pricing for a particular country. Use the following fields in the response: Within the applicable price-option collection, choose the entry whose nested price.currency equals the order’s currency_code, then send that entry’s id as price_option_id. The price option must belong to the resource identified by item_id.

Authorizations

x-api-key
string
header
required

Body

application/json

Identify the customer by providing exactly one of customer_id or customer_key. Do not send both fields.

currency_code
string
required

Three-letter ISO 4217 currency code used to price the order.

Required string length: 3
Example:

"USD"

line_items
object[]
required
Minimum array length: 1
customer_id
string<uuid>

Metrifox customer ID. Provide this or customer_key, but not both.

customer_key
string

Your immutable customer identifier. Provide this or customer_id, but not both.

Example:

"customer-123"

is_manual
boolean | null
default:true

Whether the order is manually initiated.

skip_invoice
boolean
default:false

When true, do not generate an invoice for the order.

subscription_id
string<uuid> | null

Existing subscription associated with this order.

custom_start_date
string<date-time> | null

Custom date and time at which subscription provisioning should begin.

billing_interval
enum<string> | null

Billing cadence. Provide billing_interval_value with this field.

Available options:
daily,
weekly,
monthly,
quarterly,
biannually,
yearly,
once
billing_interval_value
integer | null

Number of billing intervals. Provide billing_interval with this field.

Required range: x >= 1
status
enum<string>
default:pending

Initial order status. Draft orders are saved without invoicing or provisioning.

Available options:
pending,
draft
transitioning_subscription_id
string<uuid> | null

Subscription being changed or migrated by this order.

change_type
enum<string> | null

Type of subscription change represented by the order.

Available options:
quantity_upgrade,
quantity_downgrade,
upgrade,
downgrade,
addon_add,
addon_remove,
plan_migration
policy
object | null

Plan-change policy used when transitioning an existing subscription.

manual_discount_selections
object[]

Discounts explicitly selected for this order.

Response

Order created successfully

statusCode
integer
Example:

201

message
string
Example:

"Order Created Successfully"

meta
object
data
object
errors
object