Create Price

POST

/api/:account_id/prices/

POST

/api/:account_id/prices/

$ curl -X POST https://app.paymentkit.com/api/account_id/prices/ \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "product_id": "prod_9f8e7d6c5b4a3",
>   "currency": "usd"
> }'

1 {
2   "id": "price_123abc456def7890",
3   "account_id": "acct_987zyx654wvu321",
4   "product_id": "prod_9f8e7d6c5b4a3",
5   "name": "Standard Monthly Plan",
6   "unit_amount_atom": 9999,
7   "currency": "usd",
8   "is_active": true,
9   "unit_label": "GB",
10   "pricing_type": "recurring",
11   "recurring_interval": "month",
12   "recurring_interval_count": 1,
13   "auto_renew": true,
14   "contract_term_multiple": 12,
15   "trial_days": 14,
16   "usage_type": "licensed",
17   "metered_id": "meter_00123abc",
18   "billing_scheme": "per_unit",
19   "tier_amount_info": {
20     "mode": "volume",
21     "amount_atoms": [
22       {
23         "unit_amount_atom": 9999,
24         "units_upto": 100,
25         "flat_amount_atom": 0
26       },
27       {
28         "unit_amount_atom": 8999,
29         "units_upto": 500,
30         "flat_amount_atom": 0
31       },
32       {
33         "unit_amount_atom": 7999,
34         "units_upto": 1000,
35         "flat_amount_atom": 0
36       },
37       {
38         "unit_amount_atom": 6999,
39         "units_upto": 1000000,
40         "flat_amount_atom": 0
41       }
42     ]
43   },
44   "prerequisite_price_ids": [
45     "price_abc123def456"
46   ],
47   "exclusive_customer_ids": [
48     "cust_0011223344"
49   ],
50   "metadata": {},
51   "created_at": "2024-01-15T09:30:00Z",
52   "updated_at": "2024-01-15T09:30:00Z",
53   "product_name": "Premium Cloud Storage",
54   "product_description": "High-speed cloud storage with 1TB capacity",
55   "custom_fields": {},
56   "quantity_divisor": 1,
57   "quantity_rounding": "ceil"
58 }

Create a new price for a product. Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Request

This endpoint expects an object.

product_idstringRequired

currencyenumRequired

ISO 4217 currency codes.

namestring or nullOptional

is_activebooleanOptionalDefaults to true

unit_labelstring or nullOptional

pricing_typeenumOptionalDefaults to one_time

recurring_intervalenum or nullOptional

recurring_interval_countinteger or nullOptional

auto_renewboolean or nullOptional

contract_term_multipleinteger or nullOptional

Number of billing intervals in a contract term (e.g., 4 for quarterly billing in 1-year contract)

trial_daysintegerOptionalDefaults to 0

usage_typeenumOptionalDefaults to licensed

metered_idstring or nullOptional

billing_schemeenumOptionalDefaults to per_unit

unit_amount_atominteger or nullOptional

tier_amount_infoobject or nullOptional

Tiered pricing configuration.

prerequisite_price_idslist of strings or nullOptional

exclusive_customer_idslist of strings or nullOptional

metadatamap from strings to any or nullOptional

custom_fieldsmap from strings to any or nullOptional

Custom field values to set on this price. Keys must match defined field keys for the price entity type. Set a key to null to delete that field's value.

quantity_divisorinteger or nullOptional

Quantity divisor must be greater than or equal to 1

quantity_roundingenumOptionalDefaults to ceil

Rounding mode for fractional billable units. ‘ceil’ (default) rounds up for packaged pricing. ‘proportional’ keeps exact fractions for percentage-based fees. ‘floor’ rounds down. ‘round’ uses standard rounding.

Response

Successful Response

idstring

account_idstring

product_idstring

namestring or null

unit_amount_atominteger or null

currencyenum

ISO 4217 currency codes.

is_activeboolean

unit_labelstring or null

pricing_typestring

recurring_intervalstring or null

recurring_interval_countinteger or null

auto_renewboolean or null

contract_term_multipleinteger or null

trial_daysinteger

usage_typestring

metered_idstring or null

billing_schemestring

tier_amount_infoobject or null

Tiered pricing configuration.

prerequisite_price_idslist of strings or null

exclusive_customer_idslist of strings or null

metadatamap from strings to any or null

created_atdatetime

updated_atdatetime

product_namestring or nullOptional

product_descriptionstring or nullOptional

custom_fieldsmap from strings to any or nullOptional

Custom field values. Only included when expand=custom_fields is specified.

quantity_divisorintegerOptionalDefaults to 1

quantity_roundingenumOptional

Rounding mode for fractional billable units in metered pricing.

CEIL (default): Round up to next whole unit — for packaged pricing
PROPORTIONAL: Keep exact fractions — for percentage-based fees (e.g., 0.65% of volume)
FLOOR: Round down to whole unit
ROUND: Standard rounding (0.5+ rounds up)

Errors

422

Unprocessable Entity Error