API reference

Prices

Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products. Products help you track inventory or provisioning, and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. This approach lets you change prices without having to change your provisioning scheme. For example, you might have a single "gold" product that has prices for $10/month, $100/year, and €9 once. Related guides: Set up a subscription, create an invoice, and more about products and prices.

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Create a price

POST/v1/prices

Creates a new Price for an existing Product. The Price can be recurring or one-time.

Body parameters

  • currencystringRequired

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • activeboolean

    Whether the price can be used for new purchases. Defaults to true.

  • billing_schemestring

    Describes how to compute the price per period. Either per_unit or tiered. per_unit indicates that the fixed amount (specified in unit_amount or unit_amount_decimal) will be charged per unit in quantity (for prices with usage_type=licensed), or per unit of total usage (for prices with usage_type=metered). tiered indicates that the unit pricing will be computed using a tiering strategy as defined using the tiers and tiers_mode attributes.

    Possible values
    • per_unit
    • tiered
  • currency_optionsobject

    Prices defined in each available currency option. Each key must be a three-letter ISO currency code and a supported currency.

  • custom_unit_amountobject

    When set, provides configuration for the amount to be adjusted by the customer during Checkout Sessions and Payment Links.

    Show 4 child parameters
    • enabledbooleanRequired
    • maximuminteger
    • minimuminteger
    • presetinteger
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • lookup_keystring

    A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • nicknamestring

    A brief description of the price, hidden from customers.

  • productstring

    The ID of the Product that this Price will belong to.

  • product_dataobject

    These fields can be used to create a new product that this price will belong to.

    Show 7 child parameters
    • namestringRequired
    • activeboolean
    • idstring
    • metadataobject
    • statement_descriptorstring
    • tax_codestring
    • unit_labelstring
  • recurringobject

    The recurring components of a price such as interval and usage_type.

    Show 4 child parameters
    • intervalstringRequired
      Possible values
      • day
      • month
      • week
      • year
    • interval_countinteger
    • meterstring
    • usage_typestring
      Possible values
      • licensed
      • metered
  • tax_behaviorstring

    Only required if a default tax behavior) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.

    Possible values
    • exclusive
    • inclusive
    • unspecified
  • tiersarray of objects

    Each element represents a pricing tier. This parameter requires billing_scheme to be set to tiered. See also the documentation for billing_scheme.

    Show 5 child parameters
    • up_tostring | integerRequired
      Possible values
      • inf
    • flat_amountinteger
    • flat_amount_decimalstring
    • unit_amountinteger
    • unit_amount_decimalstring
  • tiers_modestring

    Defines if the tiering price should be graduated or volume based. In volume-based tiering, the maximum quantity within a period determines the per unit price, in graduated tiering pricing can successively change as the quantity grows.

    Possible values
    • graduated
    • volume
  • transfer_lookup_keyboolean

    If set to true, will atomically remove the lookup key from the existing price, and assign it to this price.

  • transform_quantityobject

    Apply a transformation to the reported usage or set quantity before computing the billed price. Cannot be combined with tiers.

    Show 2 child parameters
    • divide_byintegerRequired
    • roundstringRequired
      Possible values
      • down
      • up
  • unit_amountinteger

    A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. One of unit_amount, unit_amount_decimal, or custom_unit_amount is required, unless billing_scheme=tiered.

  • unit_amount_decimalstring

    Same as unit_amount, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.

Returns

The price object.

POST /v1/prices
curl https://api.knoxapi.com/v1/prices \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d currency=usd
Response
{
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1234567890,
  "currency": "usd",
  "custom_unit_amount": {
    "maximum": null,
    "minimum": null,
    "preset": null
  },
  "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
  "livemode": false,
  "lookup_key": null,
  "metadata": {},
  "nickname": null,
  "object": "price",
  "product": "prod_QXg1hqf4jFNsqG",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "meter": null,
    "usage_type": "licensed",
    "trial_period_days": null
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": {
    "divide_by": 1592560163,
    "round": "down"
  },
  "type": "recurring",
  "unit_amount": 2000,
  "unit_amount_decimal": "2000"
}

List all prices

GET/v1/prices

Returns a list of your active prices, excluding inline prices. For the list of inactive prices, set active to false.

Query parameters

  • activeboolean

    Only return prices that are active or inactive (e.g., pass false to list all inactive prices).

  • createdobject | integer

    A filter on the list, based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with a number of different query options.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • currencystring

    Only return prices for the given currency.

  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • lookup_keysarray of strings

    Only return the price with these lookup_keys, if any exist. You can specify up to 10 lookup_keys.

  • productstring

    Only return prices for the given product.

  • recurringobject

    Only return prices with these recurring fields.

    Show 3 child parameters
    • intervalstring
      Possible values
      • day
      • month
      • week
      • year
    • meterstring
    • usage_typestring
      Possible values
      • licensed
      • metered
  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

  • typestring

    Only return prices of type recurring or one_time.

    Possible values
    • one_time
    • recurring

Returns

A list of price objects.

GET /v1/prices
curl -G https://api.knoxapi.com/v1/prices \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/prices",
  "has_more": false,
  "data": [
    {
      "active": true,
      "billing_scheme": "per_unit",
      "created": 1234567890,
      "currency": "usd",
      "custom_unit_amount": {
        "maximum": null,
        "minimum": null,
        "preset": null
      },
      "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
      "livemode": false,
      "lookup_key": null,
      "metadata": {},
      "nickname": null,
      "object": "price",
      "product": "prod_QXg1hqf4jFNsqG",
      "recurring": {
        "interval": "month",
        "interval_count": 1,
        "meter": null,
        "usage_type": "licensed",
        "trial_period_days": null
      },
      "tax_behavior": "unspecified",
      "tiers_mode": null,
      "transform_quantity": {
        "divide_by": 1592560163,
        "round": "down"
      },
      "type": "recurring",
      "unit_amount": 2000,
      "unit_amount_decimal": "2000"
    }
  ]
}

Search prices

GET/v1/prices/search

Search for prices you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.

Query parameters

  • querystringRequired

    The search query string. See search query language and the list of supported query fields for prices.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • pagestring

    A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Returns

A search result of price objects.

GET /v1/prices/search
curl -G https://api.knoxapi.com/v1/prices/search \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode "query=metadata['order_id']:'6735'"
Response
{
  "object": "search_result",
  "url": "/v1/prices/search",
  "has_more": false,
  "data": [
    {
      "active": true,
      "billing_scheme": "per_unit",
      "created": 1234567890,
      "currency": "usd",
      "custom_unit_amount": {
        "maximum": null,
        "minimum": null,
        "preset": null
      },
      "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
      "livemode": false,
      "lookup_key": null,
      "metadata": {},
      "nickname": null,
      "object": "price",
      "product": "prod_QXg1hqf4jFNsqG",
      "recurring": {
        "interval": "month",
        "interval_count": 1,
        "meter": null,
        "usage_type": "licensed",
        "trial_period_days": null
      },
      "tax_behavior": "unspecified",
      "tiers_mode": null,
      "transform_quantity": {
        "divide_by": 1592560163,
        "round": "down"
      },
      "type": "recurring",
      "unit_amount": 2000,
      "unit_amount_decimal": "2000"
    }
  ],
  "next_page": null
}

Update a price

POST/v1/prices/{price}

Updates the specified price by setting the values of the parameters passed. Any parameters not provided are left unchanged.

Path parameters

  • pricestringRequired

Body parameters

  • activeboolean

    Whether the price can be used for new purchases. Defaults to true.

  • currency_optionsobject

    Prices defined in each available currency option. Each key must be a three-letter ISO currency code and a supported currency.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • lookup_keystring

    A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • nicknamestring

    A brief description of the price, hidden from customers.

  • tax_behaviorstring

    Only required if a default tax behavior) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.

    Possible values
    • exclusive
    • inclusive
    • unspecified
  • transfer_lookup_keyboolean

    If set to true, will atomically remove the lookup key from the existing price, and assign it to this price.

Returns

The price object.

POST /v1/prices/{price}
curl https://api.knoxapi.com/v1/prices/price_1PgafmB7WZ01zgkW6dKueIc5 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1234567890,
  "currency": "usd",
  "custom_unit_amount": {
    "maximum": null,
    "minimum": null,
    "preset": null
  },
  "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
  "livemode": false,
  "lookup_key": null,
  "metadata": {},
  "nickname": null,
  "object": "price",
  "product": "prod_QXg1hqf4jFNsqG",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "meter": null,
    "usage_type": "licensed",
    "trial_period_days": null
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": {
    "divide_by": 1592560163,
    "round": "down"
  },
  "type": "recurring",
  "unit_amount": 2000,
  "unit_amount_decimal": "2000"
}

Retrieve a price

GET/v1/prices/{price}

Retrieves the price with the given ID.

Path parameters

  • pricestringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The price object.

GET /v1/prices/{price}
curl https://api.knoxapi.com/v1/prices/price_1PgafmB7WZ01zgkW6dKueIc5 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1234567890,
  "currency": "usd",
  "custom_unit_amount": {
    "maximum": null,
    "minimum": null,
    "preset": null
  },
  "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
  "livemode": false,
  "lookup_key": null,
  "metadata": {},
  "nickname": null,
  "object": "price",
  "product": "prod_QXg1hqf4jFNsqG",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "meter": null,
    "usage_type": "licensed",
    "trial_period_days": null
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": {
    "divide_by": 1592560163,
    "round": "down"
  },
  "type": "recurring",
  "unit_amount": 2000,
  "unit_amount_decimal": "2000"
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.