API reference

Subscription Items

Subscription items allow you to create customer subscriptions with more than one plan, making it easy to represent complex billing relationships.

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 subscription item

POST/v1/subscription_items

Adds a new item to an existing subscription. No existing items will be changed or replaced.

Body parameters

  • subscriptionstringRequired

    The identifier of the subscription to modify.

  • billing_thresholdsobject

    Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.

    Show 1 child parameter
    • usage_gteintegerRequired
  • discountsarray of objects

    The coupons to redeem into discounts for the subscription item.

    Show 3 child parameters
    • couponstring
    • discountstring
    • promotion_codestring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

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

  • payment_behaviorstring

    Controls how Stripe handles payment when a subscription update requires payment and collection_method=charge_automatically.

    Possible values
    • allow_incomplete
    • default_incomplete
    • error_if_incomplete
    • pending_if_incomplete
  • pricestring

    The ID of the price object.

  • price_dataobject

    Data used to generate a new Price object inline.

    Show 6 child parameters
    • currencystringRequired
    • productstringRequired
    • recurringobjectRequired
      Show 2 child parameters
      • intervalstringRequired
        Possible values
        • day
        • month
        • week
        • year
      • interval_countinteger
    • tax_behaviorstring
      Possible values
      • exclusive
      • inclusive
      • unspecified
    • unit_amountinteger
    • unit_amount_decimalstring
  • proration_behaviorstring

    Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item's quantity changes. The default value is create_prorations.

    Possible values
    • always_invoice
    • create_prorations
    • none
  • proration_dateinteger

    If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply the same proration that was previewed with the upcoming invoice endpoint.

  • quantityinteger

    The quantity you'd like to apply to the subscription item you're creating.

  • tax_ratesarray of strings

    A list of Tax Rate ids. These Tax Rates will override the default_tax_rates on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.

Returns

The subscription_item object.

POST /v1/subscription_items
curl https://api.knoxapi.com/v1/subscription_items \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d subscription=sub_1Pgc6xB7WZ01zgkWJMvZp5ja
Response
{
  "created": 1721954060,
  "discounts": [],
  "id": "si_QXhVBoJ7NQdNXh",
  "metadata": {},
  "object": "subscription_item",
  "price": {
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1721948530,
    "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"
  },
  "quantity": 1,
  "subscription": "sub_1Pgc6xB7WZ01zgkWJMvZp5ja",
  "tax_rates": [],
  "plan": {
    "active": true,
    "amount": null,
    "amount_decimal": null,
    "billing_scheme": "tiered",
    "created": 1028554472,
    "currency": "currency",
    "id": "obj_123",
    "interval": "month",
    "interval_count": 797691627,
    "livemode": true,
    "metadata": null,
    "meter": null,
    "nickname": null,
    "object": "plan",
    "product": null,
    "tiers_mode": null,
    "transform_usage": {
      "divide_by": 1592560163,
      "round": "down"
    },
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "current_period_end": 976287773,
  "current_period_start": 1896570518,
  "billing_thresholds": {
    "usage_gte": null
  }
}

List all subscription items

GET/v1/subscription_items

Returns a list of your subscription items for a given subscription.

Query parameters

  • subscriptionstringRequired

    The ID of the subscription whose items will be retrieved.

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

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

Returns

A list of subscription_item objects.

GET /v1/subscription_items
curl -G https://api.knoxapi.com/v1/subscription_items \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode subscription=sub_1Pgc6xB7WZ01zgkWJMvZp5ja
Response
{
  "object": "list",
  "url": "/v1/subscription_items",
  "has_more": false,
  "data": [
    {
      "created": 1721954060,
      "discounts": [],
      "id": "si_QXhVBoJ7NQdNXh",
      "metadata": {},
      "object": "subscription_item",
      "price": {
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1721948530,
        "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"
      },
      "quantity": 1,
      "subscription": "sub_1Pgc6xB7WZ01zgkWJMvZp5ja",
      "tax_rates": [],
      "plan": {
        "active": true,
        "amount": null,
        "amount_decimal": null,
        "billing_scheme": "tiered",
        "created": 1028554472,
        "currency": "currency",
        "id": "obj_123",
        "interval": "month",
        "interval_count": 797691627,
        "livemode": true,
        "metadata": null,
        "meter": null,
        "nickname": null,
        "object": "plan",
        "product": null,
        "tiers_mode": null,
        "transform_usage": {
          "divide_by": 1592560163,
          "round": "down"
        },
        "trial_period_days": null,
        "usage_type": "licensed"
      },
      "current_period_end": 976287773,
      "current_period_start": 1896570518,
      "billing_thresholds": {
        "usage_gte": null
      }
    }
  ]
}

Update a subscription item

POST/v1/subscription_items/{item}

Updates the plan or quantity of an item on a current subscription.

Path parameters

  • itemstringRequired

Body parameters

  • billing_thresholdsobject

    Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.

    Show 1 child parameter
    • usage_gteintegerRequired
  • discountsarray of objects

    The coupons to redeem into discounts for the subscription item.

    Show 3 child parameters
    • couponstring
    • discountstring
    • promotion_codestring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

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

  • off_sessionboolean

    Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to false (on-session).

  • payment_behaviorstring

    Controls how Stripe handles payment when a subscription update requires payment and collection_method=charge_automatically.

    Possible values
    • allow_incomplete
    • default_incomplete
    • error_if_incomplete
    • pending_if_incomplete
  • pricestring

    The ID of the price object. One of price or price_data is required. When changing a subscription item's price, quantity is set to 1 unless a quantity parameter is provided.

  • price_dataobject

    Data used to generate a new Price object inline. One of price or price_data is required.

    Show 6 child parameters
    • currencystringRequired
    • productstringRequired
    • recurringobjectRequired
      Show 2 child parameters
      • intervalstringRequired
        Possible values
        • day
        • month
        • week
        • year
      • interval_countinteger
    • tax_behaviorstring
      Possible values
      • exclusive
      • inclusive
      • unspecified
    • unit_amountinteger
    • unit_amount_decimalstring
  • proration_behaviorstring

    Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item's quantity changes. The default value is create_prorations.

    Possible values
    • always_invoice
    • create_prorations
    • none
  • proration_dateinteger

    If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply the same proration that was previewed with the upcoming invoice endpoint.

  • quantityinteger

    The quantity you'd like to apply to the subscription item you're creating.

  • tax_ratesarray of strings

    A list of Tax Rate ids. These Tax Rates will override the default_tax_rates on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.

Returns

The subscription_item object.

POST /v1/subscription_items/{item}
curl https://api.knoxapi.com/v1/subscription_items/li_1Pgc73B7WZ01zgkWx8kcmZPK \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "created": 1721954060,
  "discounts": [],
  "id": "si_QXhVBoJ7NQdNXh",
  "metadata": {},
  "object": "subscription_item",
  "price": {
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1721948530,
    "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"
  },
  "quantity": 1,
  "subscription": "sub_1Pgc6xB7WZ01zgkWJMvZp5ja",
  "tax_rates": [],
  "plan": {
    "active": true,
    "amount": null,
    "amount_decimal": null,
    "billing_scheme": "tiered",
    "created": 1028554472,
    "currency": "currency",
    "id": "obj_123",
    "interval": "month",
    "interval_count": 797691627,
    "livemode": true,
    "metadata": null,
    "meter": null,
    "nickname": null,
    "object": "plan",
    "product": null,
    "tiers_mode": null,
    "transform_usage": {
      "divide_by": 1592560163,
      "round": "down"
    },
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "current_period_end": 976287773,
  "current_period_start": 1896570518,
  "billing_thresholds": {
    "usage_gte": null
  }
}

Retrieve a subscription item

GET/v1/subscription_items/{item}

Retrieves the subscription item with the given ID.

Path parameters

  • itemstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The subscription_item object.

GET /v1/subscription_items/{item}
curl https://api.knoxapi.com/v1/subscription_items/li_1Pgc73B7WZ01zgkWx8kcmZPK \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1721954060,
  "discounts": [],
  "id": "si_QXhVBoJ7NQdNXh",
  "metadata": {},
  "object": "subscription_item",
  "price": {
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1721948530,
    "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"
  },
  "quantity": 1,
  "subscription": "sub_1Pgc6xB7WZ01zgkWJMvZp5ja",
  "tax_rates": [],
  "plan": {
    "active": true,
    "amount": null,
    "amount_decimal": null,
    "billing_scheme": "tiered",
    "created": 1028554472,
    "currency": "currency",
    "id": "obj_123",
    "interval": "month",
    "interval_count": 797691627,
    "livemode": true,
    "metadata": null,
    "meter": null,
    "nickname": null,
    "object": "plan",
    "product": null,
    "tiers_mode": null,
    "transform_usage": {
      "divide_by": 1592560163,
      "round": "down"
    },
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "current_period_end": 976287773,
  "current_period_start": 1896570518,
  "billing_thresholds": {
    "usage_gte": null
  }
}

Delete a subscription item

DELETE/v1/subscription_items/{item}

Deletes an item from the subscription. Removing a subscription item from a subscription will not cancel the subscription.

Path parameters

  • itemstringRequired

Body parameters

  • clear_usageboolean

    Delete all usage for the given subscription item. Allowed only when the current plan's usage_type is metered.

  • payment_behaviorstring

    Controls how Stripe handles payment when a subscription update requires payment and collection_method=charge_automatically.

    Possible values
    • allow_incomplete
    • default_incomplete
    • error_if_incomplete
    • pending_if_incomplete
  • proration_behaviorstring

    Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item's quantity changes. The default value is create_prorations.

    Possible values
    • always_invoice
    • create_prorations
    • none
  • proration_dateinteger

    If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply the same proration that was previewed with the upcoming invoice endpoint.

Returns

The deleted_subscription_item object.

DELETE /v1/subscription_items/{item}
curl -X DELETE https://api.knoxapi.com/v1/subscription_items/li_1Pgc73B7WZ01zgkWx8kcmZPK \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "si_QXhVBoJ7NQdNXh",
  "object": "subscription_item"
}

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.