API reference

Subscription Schedules

A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes. Related guide: Subscription schedules

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 schedule

POST/v1/subscription_schedules

Creates a new subscription schedule object. Each customer can have up to 500 active or scheduled subscriptions.

Body parameters

  • billing_modeobject

    Controls how prorations and invoices for subscriptions are calculated and orchestrated.

    Show 2 child parameters
    • typestringRequired
      Possible values
      • classic
      • flexible
    • flexibleobject
      Show 1 child parameter
      • proration_discountsstring
        Possible values
        • included
        • itemized
  • customerstring

    The identifier of the customer to create the subscription schedule for.

  • customer_accountstring

    The identifier of the account to create the subscription schedule for.

  • default_settingsobject

    Object representing the subscription schedule's default settings.

    Show 10 child parameters
    • application_fee_percentnumber
    • automatic_taxobject
      Show 2 child parameters
      • enabledbooleanRequired
      • liabilityobject

        Child parameters are listed in the OpenAPI document.

    • billing_cycle_anchorstring
      Possible values
      • automatic
      • phase_start
    • billing_thresholdsobject
      Show 2 child parameters
      • amount_gteinteger
      • reset_billing_cycle_anchorboolean
    • collection_methodstring
      Possible values
      • charge_automatically
      • send_invoice
    • default_payment_methodstring
    • descriptionstring
    • invoice_settingsobject
      Show 6 child parameters
      • account_tax_idsarray of strings
      • custom_fieldsarray of objects

        Child parameters are listed in the OpenAPI document.

      • days_until_dueinteger
      • descriptionstring
      • footerstring
      • issuerobject

        Child parameters are listed in the OpenAPI document.

    • on_behalf_ofstring
    • transfer_dataobject
      Show 2 child parameters
      • destinationstringRequired
      • amount_percentnumber
  • end_behaviorstring

    Behavior of the subscription schedule and underlying subscription when it ends. Possible values are release or cancel with the default being release. release will end the subscription schedule and keep the underlying subscription running. cancel will end the subscription schedule and cancel the underlying subscription.

    Possible values
    • cancel
    • none
    • release
    • renew
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • from_subscriptionstring

    Migrate an existing subscription to be managed by a subscription schedule. If this parameter is set, a subscription schedule will be created using the subscription's item(s), set to auto-renew using the subscription's interval. When using this parameter, other parameters (such as phase values) cannot be set. To create a subscription schedule with other modifications, we recommend making two separate API calls.

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

  • phasesarray of objects

    List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the end_date of one phase will always equal the start_date of the next phase.

    Show 21 child parameters
    • itemsarray of objectsRequired
      Show 7 child parameters
      • billing_thresholdsobject

        Child parameters are listed in the OpenAPI document.

      • discountsarray of objects

        Child parameters are listed in the OpenAPI document.

      • metadataobject
      • pricestring
      • price_dataobject

        Child parameters are listed in the OpenAPI document.

      • quantityinteger
      • tax_ratesarray of strings
    • add_invoice_itemsarray of objects
      Show 8 child parameters
      • discountableboolean
      • discountsarray of objects

        Child parameters are listed in the OpenAPI document.

      • metadataobject
      • periodobject

        Child parameters are listed in the OpenAPI document.

      • pricestring
      • price_dataobject

        Child parameters are listed in the OpenAPI document.

      • quantityinteger
      • tax_ratesarray of strings
    • application_fee_percentnumber
    • automatic_taxobject
      Show 2 child parameters
      • enabledbooleanRequired
      • liabilityobject

        Child parameters are listed in the OpenAPI document.

    • billing_cycle_anchorstring
      Possible values
      • automatic
      • phase_start
    • billing_thresholdsobject
      Show 2 child parameters
      • amount_gteinteger
      • reset_billing_cycle_anchorboolean
    • collection_methodstring
      Possible values
      • charge_automatically
      • send_invoice
    • currencystring
    • default_payment_methodstring
    • default_tax_ratesarray of strings
    • descriptionstring
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • durationobject
      Show 2 child parameters
      • intervalstringRequired
        Possible values
        • day
        • month
        • week
        • year
      • interval_countinteger
    • end_dateinteger
    • invoice_settingsobject
      Show 6 child parameters
      • account_tax_idsarray of strings
      • custom_fieldsarray of objects

        Child parameters are listed in the OpenAPI document.

      • days_until_dueinteger
      • descriptionstring
      • footerstring
      • issuerobject

        Child parameters are listed in the OpenAPI document.

    • metadataobject
    • on_behalf_ofstring
    • proration_behaviorstring
      Possible values
      • always_invoice
      • create_prorations
      • none
    • transfer_dataobject
      Show 2 child parameters
      • destinationstringRequired
      • amount_percentnumber
    • trialboolean
    • trial_endinteger
  • start_dateinteger | string

    When the subscription schedule starts. We recommend using now so that it starts the subscription immediately, and to avoid unexpected behavior due to request delays or clock skew resulting in a slightly backdated or postdated start. You can also use a Unix timestamp to backdate the subscription so that it starts on a past date, or set a future date for the subscription to start on.

    Possible values
    • now

Returns

The subscription_schedule object.

POST /v1/subscription_schedules
curl -X POST https://api.knoxapi.com/v1/subscription_schedules \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "canceled_at": 1234567890,
  "completed_at": 1234567890,
  "created": 1234567890,
  "current_phase": {
    "end_date": 1725067410,
    "start_date": 1573629589
  },
  "customer": "cus_QXg1o8vcGmoR32",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": {
        "type": "account"
      },
      "disabled_reason": null
    },
    "billing_cycle_anchor": "automatic",
    "collection_method": "charge_automatically",
    "default_payment_method": null,
    "description": null,
    "invoice_settings": {
      "account_tax_ids": null,
      "days_until_due": null,
      "issuer": {
        "type": "self"
      },
      "custom_fields": null,
      "description": null,
      "footer": null
    },
    "on_behalf_of": null,
    "transfer_data": {
      "amount_percent": null,
      "destination": {
        "id": "obj_123",
        "object": "account"
      }
    },
    "billing_thresholds": {
      "amount_gte": null,
      "reset_billing_cycle_anchor": null
    }
  },
  "end_behavior": "release",
  "id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
  "livemode": false,
  "metadata": {},
  "object": "subscription_schedule",
  "phases": [
    {
      "add_invoice_items": [],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "collection_method": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "end_date": 1754008472,
      "invoice_settings": {
        "account_tax_ids": null,
        "days_until_due": null,
        "issuer": {
          "type": "account"
        },
        "custom_fields": null,
        "description": null,
        "footer": null
      },
      "items": [
        {
          "discounts": [],
          "metadata": {},
          "price": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "quantity": 1,
          "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"
          },
          "billing_thresholds": {
            "usage_gte": null
          }
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1722558872,
      "transfer_data": {
        "amount_percent": null,
        "destination": {
          "id": "obj_123",
          "object": "account"
        }
      },
      "trial_end": null,
      "billing_thresholds": {
        "amount_gte": null,
        "reset_billing_cycle_anchor": null
      }
    }
  ],
  "released_at": 1234567890,
  "released_subscription": null,
  "status": "not_started",
  "subscription": null,
  "test_clock": null,
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null
}

List all schedules

GET/v1/subscription_schedules

Retrieves the list of your subscription schedules.

Query parameters

  • canceled_atobject | integer

    Only return subscription schedules that were created canceled the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • completed_atobject | integer

    Only return subscription schedules that completed during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • createdobject | integer

    Only return subscription schedules that were created during the given date interval.

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

    Only return subscription schedules for the given customer. The response will not include subscription schedules for customers with a test clock attached if this parameter is not set.

  • customer_accountstring

    Only return subscription schedules for the given account.

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

  • released_atobject | integer

    Only return subscription schedules that were released during the given date interval.

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

    Only return subscription schedules that have not started yet.

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

GET /v1/subscription_schedules
curl -G https://api.knoxapi.com/v1/subscription_schedules \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/subscription_schedules",
  "has_more": false,
  "data": [
    {
      "application": null,
      "canceled_at": 1234567890,
      "completed_at": 1234567890,
      "created": 1234567890,
      "current_phase": {
        "end_date": 1725067410,
        "start_date": 1573629589
      },
      "customer": "cus_QXg1o8vcGmoR32",
      "default_settings": {
        "application_fee_percent": null,
        "automatic_tax": {
          "enabled": false,
          "liability": {
            "type": "account"
          },
          "disabled_reason": null
        },
        "billing_cycle_anchor": "automatic",
        "collection_method": "charge_automatically",
        "default_payment_method": null,
        "description": null,
        "invoice_settings": {
          "account_tax_ids": null,
          "days_until_due": null,
          "issuer": {
            "type": "self"
          },
          "custom_fields": null,
          "description": null,
          "footer": null
        },
        "on_behalf_of": null,
        "transfer_data": {
          "amount_percent": null,
          "destination": {
            "id": "obj_123",
            "object": "account"
          }
        },
        "billing_thresholds": {
          "amount_gte": null,
          "reset_billing_cycle_anchor": null
        }
      },
      "end_behavior": "release",
      "id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
      "livemode": false,
      "metadata": {},
      "object": "subscription_schedule",
      "phases": [
        {
          "add_invoice_items": [],
          "application_fee_percent": null,
          "billing_cycle_anchor": null,
          "collection_method": null,
          "currency": "usd",
          "default_payment_method": null,
          "default_tax_rates": [],
          "description": null,
          "discounts": [],
          "end_date": 1754008472,
          "invoice_settings": {
            "account_tax_ids": null,
            "days_until_due": null,
            "issuer": {
              "type": "account"
            },
            "custom_fields": null,
            "description": null,
            "footer": null
          },
          "items": [
            {
              "discounts": [],
              "metadata": {},
              "price": "price_1PgafmB7WZ01zgkW6dKueIc5",
              "quantity": 1,
              "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"
              },
              "billing_thresholds": {
                "usage_gte": null
              }
            }
          ],
          "metadata": {},
          "on_behalf_of": null,
          "proration_behavior": "create_prorations",
          "start_date": 1722558872,
          "transfer_data": {
            "amount_percent": null,
            "destination": {
              "id": "obj_123",
              "object": "account"
            }
          },
          "trial_end": null,
          "billing_thresholds": {
            "amount_gte": null,
            "reset_billing_cycle_anchor": null
          }
        }
      ],
      "released_at": 1234567890,
      "released_subscription": null,
      "status": "not_started",
      "subscription": null,
      "test_clock": null,
      "billing_mode": {
        "type": "classic",
        "flexible": {}
      },
      "customer_account": null
    }
  ]
}

Update a schedule

POST/v1/subscription_schedules/{schedule}

Updates an existing subscription schedule.

Path parameters

  • schedulestringRequired

Body parameters

  • default_settingsobject

    Object representing the subscription schedule's default settings.

    Show 10 child parameters
    • application_fee_percentnumber
    • automatic_taxobject
      Show 2 child parameters
      • enabledbooleanRequired
      • liabilityobject

        Child parameters are listed in the OpenAPI document.

    • billing_cycle_anchorstring
      Possible values
      • automatic
      • phase_start
    • billing_thresholdsobject
      Show 2 child parameters
      • amount_gteinteger
      • reset_billing_cycle_anchorboolean
    • collection_methodstring
      Possible values
      • charge_automatically
      • send_invoice
    • default_payment_methodstring
    • descriptionstring
    • invoice_settingsobject
      Show 6 child parameters
      • account_tax_idsarray of strings
      • custom_fieldsarray of objects

        Child parameters are listed in the OpenAPI document.

      • days_until_dueinteger
      • descriptionstring
      • footerstring
      • issuerobject

        Child parameters are listed in the OpenAPI document.

    • on_behalf_ofstring
    • transfer_dataobject
      Show 2 child parameters
      • destinationstringRequired
      • amount_percentnumber
  • end_behaviorstring

    Behavior of the subscription schedule and underlying subscription when it ends. Possible values are release or cancel with the default being release. release will end the subscription schedule and keep the underlying subscription running. cancel will end the subscription schedule and cancel the underlying subscription.

    Possible values
    • cancel
    • none
    • release
    • renew
  • 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.

  • phasesarray of objects

    List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the end_date of one phase will always equal the start_date of the next phase. Note that past phases can be omitted.

    Show 21 child parameters
    • itemsarray of objectsRequired
      Show 7 child parameters
      • billing_thresholdsobject

        Child parameters are listed in the OpenAPI document.

      • discountsarray of objects

        Child parameters are listed in the OpenAPI document.

      • metadataobject
      • pricestring
      • price_dataobject

        Child parameters are listed in the OpenAPI document.

      • quantityinteger
      • tax_ratesarray of strings
    • add_invoice_itemsarray of objects
      Show 8 child parameters
      • discountableboolean
      • discountsarray of objects

        Child parameters are listed in the OpenAPI document.

      • metadataobject
      • periodobject

        Child parameters are listed in the OpenAPI document.

      • pricestring
      • price_dataobject

        Child parameters are listed in the OpenAPI document.

      • quantityinteger
      • tax_ratesarray of strings
    • application_fee_percentnumber
    • automatic_taxobject
      Show 2 child parameters
      • enabledbooleanRequired
      • liabilityobject

        Child parameters are listed in the OpenAPI document.

    • billing_cycle_anchorstring
      Possible values
      • automatic
      • phase_start
    • billing_thresholdsobject
      Show 2 child parameters
      • amount_gteinteger
      • reset_billing_cycle_anchorboolean
    • collection_methodstring
      Possible values
      • charge_automatically
      • send_invoice
    • default_payment_methodstring
    • default_tax_ratesarray of strings
    • descriptionstring
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • durationobject
      Show 2 child parameters
      • intervalstringRequired
        Possible values
        • day
        • month
        • week
        • year
      • interval_countinteger
    • end_dateinteger | string
      Possible values
      • now
    • invoice_settingsobject
      Show 6 child parameters
      • account_tax_idsarray of strings
      • custom_fieldsarray of objects

        Child parameters are listed in the OpenAPI document.

      • days_until_dueinteger
      • descriptionstring
      • footerstring
      • issuerobject

        Child parameters are listed in the OpenAPI document.

    • metadataobject
    • on_behalf_ofstring
    • proration_behaviorstring
      Possible values
      • always_invoice
      • create_prorations
      • none
    • start_dateinteger | string
      Possible values
      • now
    • transfer_dataobject
      Show 2 child parameters
      • destinationstringRequired
      • amount_percentnumber
    • trialboolean
    • trial_endinteger | string
      Possible values
      • now
  • proration_behaviorstring

    If the update changes the billing configuration (item price, quantity, etc.) of the current phase, indicates how prorations from this change should be handled. The default value is create_prorations.

    Possible values
    • always_invoice
    • create_prorations
    • none

Returns

The subscription_schedule object.

POST /v1/subscription_schedules/{schedule}
curl https://api.knoxapi.com/v1/subscription_schedules/sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "application": null,
  "canceled_at": 1234567890,
  "completed_at": 1234567890,
  "created": 1234567890,
  "current_phase": {
    "end_date": 1725067410,
    "start_date": 1573629589
  },
  "customer": "cus_QXg1o8vcGmoR32",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": {
        "type": "account"
      },
      "disabled_reason": null
    },
    "billing_cycle_anchor": "automatic",
    "collection_method": "charge_automatically",
    "default_payment_method": null,
    "description": null,
    "invoice_settings": {
      "account_tax_ids": null,
      "days_until_due": null,
      "issuer": {
        "type": "self"
      },
      "custom_fields": null,
      "description": null,
      "footer": null
    },
    "on_behalf_of": null,
    "transfer_data": {
      "amount_percent": null,
      "destination": {
        "id": "obj_123",
        "object": "account"
      }
    },
    "billing_thresholds": {
      "amount_gte": null,
      "reset_billing_cycle_anchor": null
    }
  },
  "end_behavior": "release",
  "id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
  "livemode": false,
  "metadata": {},
  "object": "subscription_schedule",
  "phases": [
    {
      "add_invoice_items": [],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "collection_method": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "end_date": 1754008472,
      "invoice_settings": {
        "account_tax_ids": null,
        "days_until_due": null,
        "issuer": {
          "type": "account"
        },
        "custom_fields": null,
        "description": null,
        "footer": null
      },
      "items": [
        {
          "discounts": [],
          "metadata": {},
          "price": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "quantity": 1,
          "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"
          },
          "billing_thresholds": {
            "usage_gte": null
          }
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1722558872,
      "transfer_data": {
        "amount_percent": null,
        "destination": {
          "id": "obj_123",
          "object": "account"
        }
      },
      "trial_end": null,
      "billing_thresholds": {
        "amount_gte": null,
        "reset_billing_cycle_anchor": null
      }
    }
  ],
  "released_at": 1234567890,
  "released_subscription": null,
  "status": "not_started",
  "subscription": null,
  "test_clock": null,
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null
}

Retrieve a schedule

GET/v1/subscription_schedules/{schedule}

Retrieves the details of an existing subscription schedule. You only need to supply the unique subscription schedule identifier that was returned upon subscription schedule creation.

Path parameters

  • schedulestringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The subscription_schedule object.

GET /v1/subscription_schedules/{schedule}
curl https://api.knoxapi.com/v1/subscription_schedules/sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "canceled_at": 1234567890,
  "completed_at": 1234567890,
  "created": 1234567890,
  "current_phase": {
    "end_date": 1725067410,
    "start_date": 1573629589
  },
  "customer": "cus_QXg1o8vcGmoR32",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": {
        "type": "account"
      },
      "disabled_reason": null
    },
    "billing_cycle_anchor": "automatic",
    "collection_method": "charge_automatically",
    "default_payment_method": null,
    "description": null,
    "invoice_settings": {
      "account_tax_ids": null,
      "days_until_due": null,
      "issuer": {
        "type": "self"
      },
      "custom_fields": null,
      "description": null,
      "footer": null
    },
    "on_behalf_of": null,
    "transfer_data": {
      "amount_percent": null,
      "destination": {
        "id": "obj_123",
        "object": "account"
      }
    },
    "billing_thresholds": {
      "amount_gte": null,
      "reset_billing_cycle_anchor": null
    }
  },
  "end_behavior": "release",
  "id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
  "livemode": false,
  "metadata": {},
  "object": "subscription_schedule",
  "phases": [
    {
      "add_invoice_items": [],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "collection_method": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "end_date": 1754008472,
      "invoice_settings": {
        "account_tax_ids": null,
        "days_until_due": null,
        "issuer": {
          "type": "account"
        },
        "custom_fields": null,
        "description": null,
        "footer": null
      },
      "items": [
        {
          "discounts": [],
          "metadata": {},
          "price": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "quantity": 1,
          "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"
          },
          "billing_thresholds": {
            "usage_gte": null
          }
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1722558872,
      "transfer_data": {
        "amount_percent": null,
        "destination": {
          "id": "obj_123",
          "object": "account"
        }
      },
      "trial_end": null,
      "billing_thresholds": {
        "amount_gte": null,
        "reset_billing_cycle_anchor": null
      }
    }
  ],
  "released_at": 1234567890,
  "released_subscription": null,
  "status": "not_started",
  "subscription": null,
  "test_clock": null,
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null
}

Cancel a schedule

POST/v1/subscription_schedules/{schedule}/cancel

Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an active subscription). A subscription schedule can only be canceled if its status is not_started or active.

Path parameters

  • schedulestringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • invoice_nowboolean

    If the subscription schedule is active, indicates if a final invoice will be generated that contains any un-invoiced metered usage and new/pending proration invoice items. Defaults to true.

  • prorateboolean

    If the subscription schedule is active, indicates if the cancellation should be prorated. Defaults to true.

Returns

The subscription_schedule object.

POST /v1/subscription_schedules/{schedule}/cancel
curl -X POST https://api.knoxapi.com/v1/subscription_schedules/sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC/cancel \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "canceled_at": 1234567890,
  "completed_at": 1234567890,
  "created": 1234567890,
  "current_phase": {
    "end_date": 1725067410,
    "start_date": 1573629589
  },
  "customer": "cus_QXg1o8vcGmoR32",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": {
        "type": "account"
      },
      "disabled_reason": null
    },
    "billing_cycle_anchor": "automatic",
    "collection_method": "charge_automatically",
    "default_payment_method": null,
    "description": null,
    "invoice_settings": {
      "account_tax_ids": null,
      "days_until_due": null,
      "issuer": {
        "type": "self"
      },
      "custom_fields": null,
      "description": null,
      "footer": null
    },
    "on_behalf_of": null,
    "transfer_data": {
      "amount_percent": null,
      "destination": {
        "id": "obj_123",
        "object": "account"
      }
    },
    "billing_thresholds": {
      "amount_gte": null,
      "reset_billing_cycle_anchor": null
    }
  },
  "end_behavior": "release",
  "id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
  "livemode": false,
  "metadata": {},
  "object": "subscription_schedule",
  "phases": [
    {
      "add_invoice_items": [],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "collection_method": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "end_date": 1754008472,
      "invoice_settings": {
        "account_tax_ids": null,
        "days_until_due": null,
        "issuer": {
          "type": "account"
        },
        "custom_fields": null,
        "description": null,
        "footer": null
      },
      "items": [
        {
          "discounts": [],
          "metadata": {},
          "price": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "quantity": 1,
          "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"
          },
          "billing_thresholds": {
            "usage_gte": null
          }
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1722558872,
      "transfer_data": {
        "amount_percent": null,
        "destination": {
          "id": "obj_123",
          "object": "account"
        }
      },
      "trial_end": null,
      "billing_thresholds": {
        "amount_gte": null,
        "reset_billing_cycle_anchor": null
      }
    }
  ],
  "released_at": 1234567890,
  "released_subscription": null,
  "status": "not_started",
  "subscription": null,
  "test_clock": null,
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null
}

Release a schedule

POST/v1/subscription_schedules/{schedule}/release

Releases the subscription schedule immediately, which will stop scheduling of its phases, but leave any existing subscription in place. A schedule can only be released if its status is not_started or active. If the subscription schedule is currently associated with a subscription, releasing it will remove its subscription property and set the subscription’s ID to the released_subscription property.

Path parameters

  • schedulestringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • preserve_cancel_dateboolean

    Keep any cancellation on the subscription that the schedule has set

Returns

The subscription_schedule object.

POST /v1/subscription_schedules/{schedule}/release
curl -X POST https://api.knoxapi.com/v1/subscription_schedules/sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC/release \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "canceled_at": 1234567890,
  "completed_at": 1234567890,
  "created": 1234567890,
  "current_phase": {
    "end_date": 1725067410,
    "start_date": 1573629589
  },
  "customer": "cus_QXg1o8vcGmoR32",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": {
        "type": "account"
      },
      "disabled_reason": null
    },
    "billing_cycle_anchor": "automatic",
    "collection_method": "charge_automatically",
    "default_payment_method": null,
    "description": null,
    "invoice_settings": {
      "account_tax_ids": null,
      "days_until_due": null,
      "issuer": {
        "type": "self"
      },
      "custom_fields": null,
      "description": null,
      "footer": null
    },
    "on_behalf_of": null,
    "transfer_data": {
      "amount_percent": null,
      "destination": {
        "id": "obj_123",
        "object": "account"
      }
    },
    "billing_thresholds": {
      "amount_gte": null,
      "reset_billing_cycle_anchor": null
    }
  },
  "end_behavior": "release",
  "id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
  "livemode": false,
  "metadata": {},
  "object": "subscription_schedule",
  "phases": [
    {
      "add_invoice_items": [],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "collection_method": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "end_date": 1754008472,
      "invoice_settings": {
        "account_tax_ids": null,
        "days_until_due": null,
        "issuer": {
          "type": "account"
        },
        "custom_fields": null,
        "description": null,
        "footer": null
      },
      "items": [
        {
          "discounts": [],
          "metadata": {},
          "price": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "quantity": 1,
          "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"
          },
          "billing_thresholds": {
            "usage_gte": null
          }
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1722558872,
      "transfer_data": {
        "amount_percent": null,
        "destination": {
          "id": "obj_123",
          "object": "account"
        }
      },
      "trial_end": null,
      "billing_thresholds": {
        "amount_gte": null,
        "reset_billing_cycle_anchor": null
      }
    }
  ],
  "released_at": 1234567890,
  "released_subscription": null,
  "status": "not_started",
  "subscription": null,
  "test_clock": null,
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null
}

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.