> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Order
> Create an order for an existing customer
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:
```bash theme={null}
curl "https://api.metrifox.com/api/v1/product_catalogues/products/{product_id}" \
-H "x-api-key: $METRIFOX_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:
| `item_type` | `item_id` | Where to find `price_option_id` |
| - | - | - |
| `plan`, `addon`, or `single_purchase` | The selected `published_version.version_id` | The matching entry in `published_version.price_options` |
| `entitlement` | The selected entry's ID in `published_version.entitlements` | The matching entry in `published_version.entitlement_price_options` |
| `credit` | The selected entry's ID in `published_version.credit_attachments` | The matching entry in `published_version.credit_attachment_price_options` |
| `charge` | `published_version.charge_attachments[].charge.id` | The matching default `charge.price_option` or an entry in `charge.localized_prices[].price_options` |
| `invoice` | The existing invoice ID | Omit `price_option_id`; Metrifox derives it from the invoice carryover |
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`.
## OpenAPI
````yaml POST /api/v1/orders
openapi: 3.0.1
info:
title: Metrifox API Documentation
version: v1
description: >-
Welcome to Metrifox Platform's API documentation. This comprehensive API
suite enables seamless integration with our platform, providing secure and
efficient access to our services.
servers:
- url: https://{defaultHost}
variables:
defaultHost:
default: api.metrifox.com
security:
- api_key: []
paths:
/api/v1/orders:
post:
tags:
- Orders
summary: Create an order
description: >
Creates an order for an existing tenant customer. Provide exactly one
customer
identifier: `customer_id` or `customer_key`. Do not send both. Then
provide one
or more line items.
The API key supplied in `x-api-key` must have the `write` or `admin`
scope.
**Line-item types**
- `plan` — `item_id` is a plan offering-version ID. Only one plan is
allowed per order, with quantity `1`.
- `entitlement` — `item_id` is an entitlement ID.
- `single_purchase` — `item_id` is a one-time-purchase offering-version
ID.
- `addon` — `item_id` is an add-on offering-version ID.
- `charge` — `item_id` is a catalogue charge ID.
- `credit` — `item_id` is a credit-attachment ID.
- `invoice` — `item_id` is an existing invoice ID. Metrifox creates a
carryover item, derives its price, and uses quantity `1`.
For each priced line item, `price_option_id` must belong to the resource
identified by `item_id`, and its `price.currency` must match the order's
`currency_code`. Retrieve the product with
`GET /api/v1/product_catalogues/products/{product_id}` to find the
available
price options on each published resource version. Omit `price_option_id`
for
an `invoice` line item.
operationId: createOrder
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCreateRequest'
examples:
plan_order:
summary: Create a plan order
value:
currency_code: USD
customer_key: customer-123
line_items:
- item_type: plan
item_id: 603efd2d-1100-4bf1-a577-5a96f4847891
price_option_id: 85ba44aa-eb4f-47be-a84f-3b290488f1ca
quantity: 1
multi_item_order:
summary: Create an order with a plan, add-on, and entitlement
value:
currency_code: USD
customer_key: customer-123
billing_interval: monthly
billing_interval_value: 1
line_items:
- item_type: plan
item_id: 603efd2d-1100-4bf1-a577-5a96f4847891
price_option_id: 85ba44aa-eb4f-47be-a84f-3b290488f1ca
quantity: 1
- item_type: addon
item_id: 410e3a02-b63b-464f-bf17-80aeb394445d
price_option_id: f9c31bac-864c-413a-ab46-4b24872f909a
quantity: 2
- item_type: entitlement
item_id: 21398b99-c291-4147-9798-f1fbcc99bb76
price_option_id: 211eb88c-8bdc-43e0-a185-05f9f48492ca
quantity: 100
invoice_carryover:
summary: Carry an existing invoice into a new order
value:
currency_code: USD
customer_id: 764c80e3-ed59-44a5-ba07-7ee5ba547774
line_items:
- item_type: invoice
item_id: a27366fc-b84c-4dac-af47-b750de9b2d86
quantity: 1
responses:
'201':
description: Order created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCreateResponse'
examples:
created:
summary: Created order
value:
statusCode: 201
message: Order Created Successfully
meta: {}
data:
id: a8c9fc2f-6841-48ae-8496-ceca19be5a3d
customer_id: 764c80e3-ed59-44a5-ba07-7ee5ba547774
order_number: ORD-1042
status: pending
currency_code: USD
subtotal_in_standard_unit: 49
subtotal_before_discount_in_standard_unit: 49
discount_amount_in_standard_unit: 0
tax_amount_in_standard_unit: 0
total_in_standard_unit: 49
order_line_items:
- id: 947ac9c3-b7b6-4e52-a57d-220f835761cb
quantity: 1
unit_price: 49
total_price: 49
subtotal_before_discount: 49
discount_amount: 0
amount_before_tax: 49
tax_rate: 0
tax_amount: 0
tax_inclusive: false
name: Pro
source_type: plan
source_id: 603efd2d-1100-4bf1-a577-5a96f4847891
invoice_id: null
applied_discounts: []
order_charges: []
invoices: []
setup_intent: null
is_manual: true
is_sandbox: false
customer: {}
payment_method: null
billing_interval: monthly
billing_interval_value: 1
subscription_id: null
subscription_config: null
policy: null
should_collect_payment: true
should_collect_card: false
manual_discount_selections: []
created_at: '2026-10-07T09:30:00Z'
updated_at: '2026-10-07T09:30:00Z'
errors: {}
'400':
description: Invalid order data or line item
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing, invalid, revoked, or read-only API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Customer, line-item resource, or price option not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Order could not be processed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codeSamples:
- lang: curl
label: cURL
source: |
curl -X POST https://api.metrifox.com/api/v1/orders \
-H "x-api-key: $METRIFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"currency_code": "USD",
"customer_key": "customer-123",
"line_items": [
{
"item_type": "plan",
"item_id": "603efd2d-1100-4bf1-a577-5a96f4847891",
"price_option_id": "85ba44aa-eb4f-47be-a84f-3b290488f1ca",
"quantity": 1
}
]
}'
components:
schemas:
OrderCreateRequest:
type: object
description: |
Identify the customer by providing exactly one of `customer_id` or
`customer_key`. Do not send both fields.
required:
- currency_code
- line_items
properties:
currency_code:
type: string
minLength: 3
maxLength: 3
description: Three-letter ISO 4217 currency code used to price the order.
example: USD
customer_id:
type: string
format: uuid
description: Metrifox customer ID. Provide this or `customer_key`, but not both.
customer_key:
type: string
description: >-
Your immutable customer identifier. Provide this or `customer_id`,
but not both.
example: customer-123
line_items:
type: array
minItems: 1
items:
$ref: '#/components/schemas/OrderLineItemCreateRequest'
is_manual:
type: boolean
nullable: true
default: true
description: Whether the order is manually initiated.
skip_invoice:
type: boolean
default: false
description: When true, do not generate an invoice for the order.
subscription_id:
type: string
format: uuid
nullable: true
description: Existing subscription associated with this order.
custom_start_date:
type: string
format: date-time
nullable: true
description: >-
Custom date and time at which subscription provisioning should
begin.
billing_interval:
type: string
enum:
- daily
- weekly
- monthly
- quarterly
- biannually
- yearly
- once
nullable: true
description: Billing cadence. Provide `billing_interval_value` with this field.
billing_interval_value:
type: integer
minimum: 1
nullable: true
description: >-
Number of billing intervals. Provide `billing_interval` with this
field.
status:
type: string
enum:
- pending
- draft
default: pending
description: >-
Initial order status. Draft orders are saved without invoicing or
provisioning.
transitioning_subscription_id:
type: string
format: uuid
nullable: true
description: Subscription being changed or migrated by this order.
change_type:
type: string
nullable: true
enum:
- quantity_upgrade
- quantity_downgrade
- upgrade
- downgrade
- addon_add
- addon_remove
- plan_migration
description: Type of subscription change represented by the order.
policy:
type: object
nullable: true
additionalProperties: true
description: Plan-change policy used when transitioning an existing subscription.
manual_discount_selections:
type: array
default: []
items:
$ref: '#/components/schemas/ManualDiscountSelectionRequest'
description: Discounts explicitly selected for this order.
OrderCreateResponse:
type: object
properties:
statusCode:
type: integer
example: 201
message:
type: string
example: Order Created Successfully
meta:
type: object
additionalProperties: true
data:
$ref: '#/components/schemas/Order'
errors:
type: object
additionalProperties: true
ErrorResponse:
type: object
properties:
message:
type: string
description: Error message
errors:
type: object
additionalProperties: true
description: Detailed error information
OrderLineItemCreateRequest:
type: object
required:
- item_type
- item_id
- quantity
properties:
item_type:
type: string
enum:
- plan
- entitlement
- single_purchase
- addon
- charge
- credit
- invoice
description: |
Type of resource referenced by `item_id`:
- `plan`: a plan offering version
- `entitlement`: a product entitlement
- `single_purchase`: a one-time-purchase offering version
- `addon`: an add-on offering version
- `charge`: a catalogue charge
- `credit`: a credit attachment
- `invoice`: an existing invoice to carry into this order
example: plan
item_id:
type: string
format: uuid
description: ID of the resource selected by `item_type`.
example: 603efd2d-1100-4bf1-a577-5a96f4847891
price_option_id:
type: string
format: uuid
nullable: true
description: >
For a priced line item, use the ID of the selected resource's price
option
whose `price.currency` matches the order's `currency_code`. Retrieve
the
product with `GET /api/v1/product_catalogues/products/{product_id}`
and
select the applicable option from the resource's published version.
See
the Create Order guide for the response field used by each
`item_type`.
Omit this for an `invoice` line item; Metrifox derives the price
from the
invoice carryover.
example: 85ba44aa-eb4f-47be-a84f-3b290488f1ca
quantity:
type: integer
minimum: 1
description: >-
Number of units. A `plan` must have quantity `1`; an `invoice` is
always processed with quantity `1`.
example: 1
metadata:
type: object
additionalProperties: true
default: {}
description: Optional application-specific metadata for the line item.
ManualDiscountSelectionRequest:
type: object
required:
- discount_id
properties:
discount_id:
type: string
format: uuid
description: ID of the discount to apply.
line_item_ids:
type: array
items:
type: string
default: []
description: Existing line-item IDs targeted by the discount.
price_option_ids:
type: array
items:
type: string
format: uuid
default: []
description: Price-option IDs targeted by the discount.
Order:
type: object
properties:
id:
type: string
format: uuid
customer_id:
type: string
format: uuid
order_number:
type: string
nullable: true
status:
type: string
enum:
- draft
- pending
- fulfilled
- partially_fulfilled
- refunded
- failed
- cancelled
- abandoned
- deleted
currency_code:
type: string
subtotal_in_standard_unit:
type: number
format: double
subtotal_before_discount_in_standard_unit:
type: number
format: double
discount_amount_in_standard_unit:
type: number
format: double
tax_amount_in_standard_unit:
type: number
format: double
total_in_standard_unit:
type: number
format: double
order_line_items:
type: array
items:
$ref: '#/components/schemas/OrderLineItem'
applied_discounts:
type: array
items:
type: object
additionalProperties: true
order_charges:
type: array
nullable: true
items:
type: object
additionalProperties: true
invoices:
type: array
nullable: true
items:
type: object
additionalProperties: true
setup_intent:
type: object
nullable: true
additionalProperties: true
is_manual:
type: boolean
is_sandbox:
type: boolean
customer:
type: object
additionalProperties: true
payment_method:
type: string
nullable: true
billing_interval:
type: string
nullable: true
billing_interval_value:
type: integer
nullable: true
subscription_id:
type: string
format: uuid
nullable: true
subscription_config:
type: object
nullable: true
additionalProperties: true
policy:
type: object
nullable: true
additionalProperties: true
should_collect_payment:
type: boolean
should_collect_card:
type: boolean
manual_discount_selections:
type: array
items:
type: object
additionalProperties: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
OrderLineItem:
type: object
properties:
id:
type: string
format: uuid
quantity:
type: integer
unit_price:
type: number
format: double
total_price:
type: number
format: double
subtotal_before_discount:
type: number
format: double
discount_amount:
type: number
format: double
amount_before_tax:
type: number
format: double
tax_rate:
type: number
format: double
tax_amount:
type: number
format: double
tax_inclusive:
type: boolean
name:
type: string
nullable: true
source_type:
type: string
description: >-
Normalized source type, such as `plan`, `addon`, `entitlement`,
`single_purchase`, `charge`, `credit`, or `invoice_carryover`.
source_id:
type: string
format: uuid
invoice_id:
type: string
format: uuid
nullable: true
price_option:
type: object
nullable: true
additionalProperties: true
securitySchemes:
api_key:
type: apiKey
name: x-api-key
in: header
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.