API reference

Billing

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 billing alert

POST/v1/billing/alerts

Creates a billing alert

Body parameters

  • alert_typestringRequired

    The type of alert to create.

    Possible values
    • usage_threshold
  • titlestringRequired

    The title of the alert.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • usage_thresholdobject

    The configuration of the usage threshold.

    Show 4 child parameters
    • gteintegerRequired
    • meterstringRequired
    • recurrencestringRequired
      Possible values
      • one_time
    • filtersarray of objects
      Show 2 child parameters
      • typestringRequired
        Possible values
        • customer
      • customerstring

Returns

The billing.alert object.

POST /v1/billing/alerts
curl https://api.knoxapi.com/v1/billing/alerts \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d alert_type=usage_threshold \
  -d title=title
Response
{
  "alert_type": "usage_threshold",
  "id": "obj_123",
  "livemode": true,
  "object": "billing.alert",
  "status": null,
  "title": "title",
  "usage_threshold": {
    "filters": null,
    "gte": 102680,
    "meter": {
      "created": 1028554472,
      "customer_mapping": {
        "event_payload_key": "event_payload_key",
        "type": "by_id"
      },
      "default_aggregation": {
        "formula": "sum"
      },
      "display_name": "display_name",
      "event_name": "event_name",
      "event_time_window": null,
      "id": "obj_123",
      "livemode": true,
      "object": "billing.meter",
      "status": "active",
      "status_transitions": {
        "deactivated_at": null
      },
      "updated": 234430277,
      "value_settings": {
        "event_payload_key": "event_payload_key"
      }
    },
    "recurrence": "one_time"
  }
}

List billing alerts

GET/v1/billing/alerts

Lists billing active and inactive alerts

Query parameters

  • alert_typestring

    Filter results to only include this type of alert.

    Possible values
    • usage_threshold
  • 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.

  • meterstring

    Filter results to only include alerts with the given meter.

  • 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 billing.alert objects.

GET /v1/billing/alerts
curl -G https://api.knoxapi.com/v1/billing/alerts \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/billing/alerts",
  "has_more": false,
  "data": [
    {
      "alert_type": "usage_threshold",
      "id": "obj_123",
      "livemode": true,
      "object": "billing.alert",
      "status": null,
      "title": "title",
      "usage_threshold": {
        "filters": null,
        "gte": 102680,
        "meter": {
          "created": 1028554472,
          "customer_mapping": {
            "event_payload_key": "event_payload_key",
            "type": "by_id"
          },
          "default_aggregation": {
            "formula": "sum"
          },
          "display_name": "display_name",
          "event_name": "event_name",
          "event_time_window": null,
          "id": "obj_123",
          "livemode": true,
          "object": "billing.meter",
          "status": "active",
          "status_transitions": {
            "deactivated_at": null
          },
          "updated": 234430277,
          "value_settings": {
            "event_payload_key": "event_payload_key"
          }
        },
        "recurrence": "one_time"
      }
    }
  ]
}

Retrieve the credit balance summary for a customer

GET/v1/billing/credit_balance_summary

Retrieves the credit balance summary for a customer.

Query parameters

  • filterobjectRequired

    The filter criteria for the credit balance summary.

    Show 3 child parameters
    • typestringRequired
      Possible values
      • applicability_scope
      • credit_grant
    • applicability_scopeobject
      Show 2 child parameters
      • price_typestring
        Possible values
        • metered
      • pricesarray of objects

        Child parameters are listed in the OpenAPI document.

    • credit_grantstring
  • customerstring

    The customer whose credit balance summary you're retrieving.

  • customer_accountstring

    The account representing the customer whose credit balance summary you're retrieving.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.credit_balance_summary object.

GET /v1/billing/credit_balance_summary
curl -G https://api.knoxapi.com/v1/billing/credit_balance_summary \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode "filter[type]=applicability_scope"
Response
{
  "balances": [
    {
      "available_balance": {
        "monetary": {
          "currency": "currency",
          "value": 111972721
        },
        "type": "monetary"
      },
      "ledger_balance": {
        "monetary": {
          "currency": "currency",
          "value": 111972721
        },
        "type": "monetary"
      }
    }
  ],
  "customer": {
    "created": 1028554472,
    "default_source": null,
    "description": null,
    "email": null,
    "id": "obj_123",
    "livemode": true,
    "object": "customer",
    "shipping": {}
  },
  "livemode": true,
  "object": "billing.credit_balance_summary",
  "customer_account": null
}

List credit balance transactions

GET/v1/billing/credit_balance_transactions

Retrieve a list of credit balance transactions.

Query parameters

  • credit_grantstring

    The credit grant for which to fetch credit balance transactions.

  • customerstring

    The customer whose credit balance transactions you're retrieving.

  • customer_accountstring

    The account representing the customer whose credit balance transactions you're retrieving.

  • 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 billing.credit_balance_transaction objects.

GET /v1/billing/credit_balance_transactions
curl -G https://api.knoxapi.com/v1/billing/credit_balance_transactions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/billing/credit_balance_transactions",
  "has_more": false,
  "data": [
    {
      "created": 1028554472,
      "credit": {
        "amount": {
          "monetary": {
            "currency": "currency",
            "value": 111972721
          },
          "type": "monetary"
        },
        "credits_application_invoice_voided": {
          "invoice": "invoice",
          "invoice_line_item": "invoice_line_item"
        },
        "type": "credits_application_invoice_voided"
      },
      "credit_grant": "credit_grant",
      "debit": {
        "amount": {
          "monetary": {
            "currency": "currency",
            "value": 111972721
          },
          "type": "monetary"
        },
        "credits_applied": {
          "invoice": "invoice",
          "invoice_line_item": "invoice_line_item"
        },
        "type": "credits_applied"
      },
      "effective_at": 247108043,
      "id": "obj_123",
      "livemode": true,
      "object": "billing.credit_balance_transaction",
      "test_clock": null,
      "type": null
    }
  ]
}

Create a credit grant

POST/v1/billing/credit_grants

Creates a credit grant.

Body parameters

  • amountobjectRequired

    Amount of this credit grant.

    Show 2 child parameters
    • typestringRequired
      Possible values
      • monetary
    • monetaryobject
      Show 2 child parameters
      • currencystringRequired
      • valueintegerRequired
  • applicability_configobjectRequired

    Configuration specifying what this credit grant applies to. We currently only support metered prices that have a Billing Meter attached to them.

    Show 1 child parameter
    • scopeobjectRequired
      Show 2 child parameters
      • price_typestring
        Possible values
        • metered
      • pricesarray of objects

        Child parameters are listed in the OpenAPI document.

  • categorystring

    The category of this credit grant. It defaults to paid if not specified.

    Possible values
    • paid
    • promotional
  • customerstring

    ID of the customer receiving the billing credits.

  • customer_accountstring

    ID of the account representing the customer receiving the billing credits.

  • effective_atinteger

    The time when the billing credits become effective-when they're eligible for use. It defaults to the current timestamp if not specified.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • expires_atinteger

    The time when the billing credits expire. If not specified, the billing credits don't expire.

  • metadataobject

    Set of key-value pairs that you can attach to an object. You can use this to store additional information about the object (for example, cost basis) in a structured format.

  • namestring

    A descriptive name shown in the Dashboard.

  • priorityinteger

    The desired priority for applying this credit grant. If not specified, it will be set to the default value of 50. The highest priority is 0 and the lowest is 100.

Returns

The billing.credit_grant object.

POST /v1/billing/credit_grants
curl https://api.knoxapi.com/v1/billing/credit_grants \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "amount[type]=monetary" \
  -d "applicability_config[scope]="
Response
{
  "amount": {
    "monetary": {
      "currency": "currency",
      "value": 111972721
    },
    "type": "monetary"
  },
  "applicability_config": {
    "scope": {
      "price_type": "metered"
    }
  },
  "category": "paid",
  "created": 1028554472,
  "customer": {
    "created": 1028554472,
    "default_source": null,
    "description": null,
    "email": null,
    "id": "obj_123",
    "livemode": true,
    "object": "customer",
    "shipping": {}
  },
  "effective_at": null,
  "expires_at": null,
  "id": "obj_123",
  "livemode": true,
  "metadata": {
    "undefined": "metadata"
  },
  "name": null,
  "object": "billing.credit_grant",
  "test_clock": null,
  "updated": 234430277,
  "voided_at": null,
  "customer_account": null,
  "priority": 50
}

List credit grants

GET/v1/billing/credit_grants

Retrieve a list of credit grants.

Query parameters

  • customerstring

    Only return credit grants for this customer.

  • customer_accountstring

    Only return credit grants for this account representing the customer.

  • 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 billing.credit_grant objects.

GET /v1/billing/credit_grants
curl -G https://api.knoxapi.com/v1/billing/credit_grants \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/billing/credit_grants",
  "has_more": false,
  "data": [
    {
      "amount": {
        "monetary": {
          "currency": "currency",
          "value": 111972721
        },
        "type": "monetary"
      },
      "applicability_config": {
        "scope": {
          "price_type": "metered"
        }
      },
      "category": "paid",
      "created": 1028554472,
      "customer": {
        "created": 1028554472,
        "default_source": null,
        "description": null,
        "email": null,
        "id": "obj_123",
        "livemode": true,
        "object": "customer",
        "shipping": {}
      },
      "effective_at": null,
      "expires_at": null,
      "id": "obj_123",
      "livemode": true,
      "metadata": {
        "undefined": "metadata"
      },
      "name": null,
      "object": "billing.credit_grant",
      "test_clock": null,
      "updated": 234430277,
      "voided_at": null,
      "customer_account": null,
      "priority": 50
    }
  ]
}

Create a feedback option

POST/v1/billing/feedback_options

Creates a new feedback option.

Body parameters

  • descriptionstringRequired
  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.feedback_option object.

POST /v1/billing/feedback_options
curl https://api.knoxapi.com/v1/billing/feedback_options \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d description=description
Response
{
  "object": "billing.feedback_option",
  "description": "description",
  "id": "obj_123",
  "livemode": true,
  "status": "active",
  "status_transitions": {
    "deactivated_at": null
  }
}

Feedback Options List API Method

GET/v1/billing/feedback_options

An API method for listing the feedback options model

Query parameters

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

  • statusstring

    Filter results to only include feedback options with the given status.

    Possible values
    • active
    • inactive

Returns

A list of billing.feedback_option objects.

GET /v1/billing/feedback_options
curl -G https://api.knoxapi.com/v1/billing/feedback_options \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/billing/feedback_options",
  "has_more": false,
  "data": [
    {
      "object": "billing.feedback_option",
      "description": "description",
      "id": "obj_123",
      "livemode": true,
      "status": "active",
      "status_transitions": {
        "deactivated_at": null
      }
    }
  ]
}

Create a billing meter event adjustment

POST/v1/billing/meter_event_adjustments

Creates a billing meter event adjustment.

Body parameters

  • event_namestringRequired

    The name of the meter event. Corresponds with the event_name field on a meter.

  • typestringRequired

    Specifies whether to cancel a single event or a range of events for a time period. Time period cancellation is not supported yet.

    Possible values
    • cancel
  • cancelobject

    Specifies which event to cancel.

    Show 1 child parameter
    • identifierstring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.meter_event_adjustment object.

POST /v1/billing/meter_event_adjustments
curl https://api.knoxapi.com/v1/billing/meter_event_adjustments \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d event_name=test-meter-event-name \
  -d type=cancel
Response
{
  "cancel": {
    "identifier": "1234-1234"
  },
  "event_name": "test-meter-event-name",
  "livemode": false,
  "object": "billing.meter_event_adjustment",
  "status": "complete",
  "type": "cancel"
}

Create a billing meter event

POST/v1/billing/meter_events

Creates a billing meter event.

Body parameters

  • event_namestringRequired

    The name of the meter event. Corresponds with the event_name field on a meter.

  • payloadobjectRequired

    The payload of the event. This must contain the fields corresponding to a meter's customer_mapping.event_payload_key (default is stripe_customer_id) and value_settings.event_payload_key (default is value). Read more about the payload.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • identifierstring

    A unique identifier for the event. If not provided, one is generated. We recommend using UUID-like identifiers. Stripe enforces uniqueness within a rolling period of at least 24 hours. The enforcement of uniqueness primarily addresses issues arising from accidental retries or other problems occurring within extremely brief time intervals. This approach helps prevent duplicate entries and ensures data integrity in high-frequency operations.

  • timestampinteger

    The time of the event. Measured in seconds since the Unix epoch. Must be within the past 35 calendar days or up to 5 minutes in the future. Defaults to current timestamp if not specified.

Returns

The billing.meter_event object.

POST /v1/billing/meter_events
curl https://api.knoxapi.com/v1/billing/meter_events \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d event_name=api_request \
  -d payload=
Response
{
  "created": 1234567890,
  "event_name": "api_request",
  "identifier": "1234-1234",
  "livemode": false,
  "object": "billing.meter_event",
  "payload": {
    "stripe_customer_id": "cus_123",
    "value": "25"
  },
  "timestamp": 1234567890
}

Create a billing meter

POST/v1/billing/meters

Creates a billing meter.

Body parameters

  • default_aggregationobjectRequired

    The default settings to aggregate a meter's events with.

    Show 1 child parameter
    • formulastringRequired
      Possible values
      • count
      • last
      • sum
  • display_namestringRequired

    The meter’s name. Not visible to the customer.

  • event_namestringRequired

    The name of the meter event to record usage for. Corresponds with the event_name field on meter events.

  • customer_mappingobject

    Fields that specify how to map a meter event to a customer.

    Show 2 child parameters
    • event_payload_keystringRequired
    • typestringRequired
      Possible values
      • by_id
  • event_time_windowstring

    The time window which meter events have been pre-aggregated for, if any.

    Possible values
    • day
    • hour
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • value_settingsobject

    Fields that specify how to calculate a meter event's value.

    Show 1 child parameter
    • event_payload_keystringRequired

Returns

The billing.meter object.

POST /v1/billing/meters
curl https://api.knoxapi.com/v1/billing/meters \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "default_aggregation[formula]=sum" \
  -d display_name=test-meter \
  -d event_name=test-meter-event-name
Response
{
  "created": 1234567890,
  "customer_mapping": {
    "event_payload_key": "customer",
    "type": "by_id"
  },
  "default_aggregation": {
    "formula": "sum"
  },
  "display_name": "test-meter",
  "event_name": "test-meter-event-name",
  "event_time_window": null,
  "id": "meter_123",
  "livemode": true,
  "object": "billing.meter",
  "status": "active",
  "status_transitions": {
    "deactivated_at": null
  },
  "updated": 1234567890,
  "value_settings": {
    "event_payload_key": "value"
  }
}

List billing meters

GET/v1/billing/meters

Retrieve a list of billing meters.

Query parameters

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

  • statusstring

    Filter results to only include meters with the given status.

    Possible values
    • active
    • inactive

Returns

A list of billing.meter objects.

GET /v1/billing/meters
curl -G https://api.knoxapi.com/v1/billing/meters \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/billing/meters",
  "has_more": false,
  "data": [
    {
      "created": 1234567890,
      "customer_mapping": {
        "event_payload_key": "customer",
        "type": "by_id"
      },
      "default_aggregation": {
        "formula": "sum"
      },
      "display_name": "test-meter",
      "event_name": "test-meter-event-name",
      "event_time_window": null,
      "id": "meter_123",
      "livemode": true,
      "object": "billing.meter",
      "status": "active",
      "status_transitions": {
        "deactivated_at": null
      },
      "updated": 1234567890,
      "value_settings": {
        "event_payload_key": "value"
      }
    }
  ]
}

Retrieve a billing alert

GET/v1/billing/alerts/{id}

Retrieves a billing alert given an ID

Path parameters

  • idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.alert object.

GET /v1/billing/alerts/{id}
curl https://api.knoxapi.com/v1/billing/alerts/obj_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "alert_type": "usage_threshold",
  "id": "obj_123",
  "livemode": true,
  "object": "billing.alert",
  "status": null,
  "title": "title",
  "usage_threshold": {
    "filters": null,
    "gte": 102680,
    "meter": {
      "created": 1028554472,
      "customer_mapping": {
        "event_payload_key": "event_payload_key",
        "type": "by_id"
      },
      "default_aggregation": {
        "formula": "sum"
      },
      "display_name": "display_name",
      "event_name": "event_name",
      "event_time_window": null,
      "id": "obj_123",
      "livemode": true,
      "object": "billing.meter",
      "status": "active",
      "status_transitions": {
        "deactivated_at": null
      },
      "updated": 234430277,
      "value_settings": {
        "event_payload_key": "event_payload_key"
      }
    },
    "recurrence": "one_time"
  }
}

Retrieve a credit balance transaction

GET/v1/billing/credit_balance_transactions/{id}

Retrieves a credit balance transaction.

Path parameters

  • idstringRequired

    Unique identifier for the object.

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.credit_balance_transaction object.

GET /v1/billing/credit_balance_transactions/{id}
curl https://api.knoxapi.com/v1/billing/credit_balance_transactions/obj_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1028554472,
  "credit": {
    "amount": {
      "monetary": {
        "currency": "currency",
        "value": 111972721
      },
      "type": "monetary"
    },
    "credits_application_invoice_voided": {
      "invoice": "invoice",
      "invoice_line_item": "invoice_line_item"
    },
    "type": "credits_application_invoice_voided"
  },
  "credit_grant": "credit_grant",
  "debit": {
    "amount": {
      "monetary": {
        "currency": "currency",
        "value": 111972721
      },
      "type": "monetary"
    },
    "credits_applied": {
      "invoice": "invoice",
      "invoice_line_item": "invoice_line_item"
    },
    "type": "credits_applied"
  },
  "effective_at": 247108043,
  "id": "obj_123",
  "livemode": true,
  "object": "billing.credit_balance_transaction",
  "test_clock": null,
  "type": null
}

Update a credit grant

POST/v1/billing/credit_grants/{id}

Updates a credit grant.

Path parameters

  • idstringRequired

    Unique identifier for the object.

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • expires_atinteger

    The time when the billing credits created by this credit grant expire. If set to empty, the billing credits never expire.

  • metadataobject

    Set of key-value pairs you can attach to an object. You can use this to store additional information about the object (for example, cost basis) in a structured format.

Returns

The billing.credit_grant object.

POST /v1/billing/credit_grants/{id}
curl https://api.knoxapi.com/v1/billing/credit_grants/obj_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "amount": {
    "monetary": {
      "currency": "currency",
      "value": 111972721
    },
    "type": "monetary"
  },
  "applicability_config": {
    "scope": {
      "price_type": "metered"
    }
  },
  "category": "paid",
  "created": 1028554472,
  "customer": {
    "created": 1028554472,
    "default_source": null,
    "description": null,
    "email": null,
    "id": "obj_123",
    "livemode": true,
    "object": "customer",
    "shipping": {}
  },
  "effective_at": null,
  "expires_at": null,
  "id": "obj_123",
  "livemode": true,
  "metadata": {
    "undefined": "metadata"
  },
  "name": null,
  "object": "billing.credit_grant",
  "test_clock": null,
  "updated": 234430277,
  "voided_at": null,
  "customer_account": null,
  "priority": 50
}

Retrieve a credit grant

GET/v1/billing/credit_grants/{id}

Retrieves a credit grant.

Path parameters

  • idstringRequired

    Unique identifier for the object.

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.credit_grant object.

GET /v1/billing/credit_grants/{id}
curl https://api.knoxapi.com/v1/billing/credit_grants/obj_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": {
    "monetary": {
      "currency": "currency",
      "value": 111972721
    },
    "type": "monetary"
  },
  "applicability_config": {
    "scope": {
      "price_type": "metered"
    }
  },
  "category": "paid",
  "created": 1028554472,
  "customer": {
    "created": 1028554472,
    "default_source": null,
    "description": null,
    "email": null,
    "id": "obj_123",
    "livemode": true,
    "object": "customer",
    "shipping": {}
  },
  "effective_at": null,
  "expires_at": null,
  "id": "obj_123",
  "livemode": true,
  "metadata": {
    "undefined": "metadata"
  },
  "name": null,
  "object": "billing.credit_grant",
  "test_clock": null,
  "updated": 234430277,
  "voided_at": null,
  "customer_account": null,
  "priority": 50
}

Update a feedback option

POST/v1/billing/feedback_options/{id}

Updates the description of an existing feedback option.

Path parameters

  • idstringRequired

Body parameters

  • descriptionstring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.feedback_option object.

POST /v1/billing/feedback_options/{id}
curl -X POST https://api.knoxapi.com/v1/billing/feedback_options/obj_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "object": "billing.feedback_option",
  "description": "description",
  "id": "obj_123",
  "livemode": true,
  "status": "active",
  "status_transitions": {
    "deactivated_at": null
  }
}

Retrieve a feedback option

GET/v1/billing/feedback_options/{id}

Retrieves a feedback options object given an ID.

Path parameters

  • idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.feedback_option object.

GET /v1/billing/feedback_options/{id}
curl https://api.knoxapi.com/v1/billing/feedback_options/obj_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "object": "billing.feedback_option",
  "description": "description",
  "id": "obj_123",
  "livemode": true,
  "status": "active",
  "status_transitions": {
    "deactivated_at": null
  }
}

Update a billing meter

POST/v1/billing/meters/{id}

Updates a billing meter.

Path parameters

  • idstringRequired

Body parameters

  • display_namestring

    The meter’s name. Not visible to the customer.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.meter object.

POST /v1/billing/meters/{id}
curl -X POST https://api.knoxapi.com/v1/billing/meters/meter_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "customer_mapping": {
    "event_payload_key": "customer",
    "type": "by_id"
  },
  "default_aggregation": {
    "formula": "sum"
  },
  "display_name": "test-meter",
  "event_name": "test-meter-event-name",
  "event_time_window": null,
  "id": "meter_123",
  "livemode": true,
  "object": "billing.meter",
  "status": "active",
  "status_transitions": {
    "deactivated_at": null
  },
  "updated": 1234567890,
  "value_settings": {
    "event_payload_key": "value"
  }
}

Retrieve a billing meter

GET/v1/billing/meters/{id}

Retrieves a billing meter given an ID.

Path parameters

  • idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.meter object.

GET /v1/billing/meters/{id}
curl https://api.knoxapi.com/v1/billing/meters/meter_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "customer_mapping": {
    "event_payload_key": "customer",
    "type": "by_id"
  },
  "default_aggregation": {
    "formula": "sum"
  },
  "display_name": "test-meter",
  "event_name": "test-meter-event-name",
  "event_time_window": null,
  "id": "meter_123",
  "livemode": true,
  "object": "billing.meter",
  "status": "active",
  "status_transitions": {
    "deactivated_at": null
  },
  "updated": 1234567890,
  "value_settings": {
    "event_payload_key": "value"
  }
}

Activate a billing alert

POST/v1/billing/alerts/{id}/activate

Reactivates this alert, allowing it to trigger again.

Path parameters

  • idstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.alert object.

POST /v1/billing/alerts/{id}/activate
curl -X POST https://api.knoxapi.com/v1/billing/alerts/obj_123/activate \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "alert_type": "usage_threshold",
  "id": "obj_123",
  "livemode": true,
  "object": "billing.alert",
  "status": null,
  "title": "title",
  "usage_threshold": {
    "filters": null,
    "gte": 102680,
    "meter": {
      "created": 1028554472,
      "customer_mapping": {
        "event_payload_key": "event_payload_key",
        "type": "by_id"
      },
      "default_aggregation": {
        "formula": "sum"
      },
      "display_name": "display_name",
      "event_name": "event_name",
      "event_time_window": null,
      "id": "obj_123",
      "livemode": true,
      "object": "billing.meter",
      "status": "active",
      "status_transitions": {
        "deactivated_at": null
      },
      "updated": 234430277,
      "value_settings": {
        "event_payload_key": "event_payload_key"
      }
    },
    "recurrence": "one_time"
  }
}

Archive a billing alert

POST/v1/billing/alerts/{id}/archive

Archives this alert, removing it from the list view and APIs. This is non-reversible.

Path parameters

  • idstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.alert object.

POST /v1/billing/alerts/{id}/archive
curl -X POST https://api.knoxapi.com/v1/billing/alerts/obj_123/archive \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "alert_type": "usage_threshold",
  "id": "obj_123",
  "livemode": true,
  "object": "billing.alert",
  "status": null,
  "title": "title",
  "usage_threshold": {
    "filters": null,
    "gte": 102680,
    "meter": {
      "created": 1028554472,
      "customer_mapping": {
        "event_payload_key": "event_payload_key",
        "type": "by_id"
      },
      "default_aggregation": {
        "formula": "sum"
      },
      "display_name": "display_name",
      "event_name": "event_name",
      "event_time_window": null,
      "id": "obj_123",
      "livemode": true,
      "object": "billing.meter",
      "status": "active",
      "status_transitions": {
        "deactivated_at": null
      },
      "updated": 234430277,
      "value_settings": {
        "event_payload_key": "event_payload_key"
      }
    },
    "recurrence": "one_time"
  }
}

Deactivate a billing alert

POST/v1/billing/alerts/{id}/deactivate

Deactivates this alert, preventing it from triggering.

Path parameters

  • idstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.alert object.

POST /v1/billing/alerts/{id}/deactivate
curl -X POST https://api.knoxapi.com/v1/billing/alerts/obj_123/deactivate \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "alert_type": "usage_threshold",
  "id": "obj_123",
  "livemode": true,
  "object": "billing.alert",
  "status": null,
  "title": "title",
  "usage_threshold": {
    "filters": null,
    "gte": 102680,
    "meter": {
      "created": 1028554472,
      "customer_mapping": {
        "event_payload_key": "event_payload_key",
        "type": "by_id"
      },
      "default_aggregation": {
        "formula": "sum"
      },
      "display_name": "display_name",
      "event_name": "event_name",
      "event_time_window": null,
      "id": "obj_123",
      "livemode": true,
      "object": "billing.meter",
      "status": "active",
      "status_transitions": {
        "deactivated_at": null
      },
      "updated": 234430277,
      "value_settings": {
        "event_payload_key": "event_payload_key"
      }
    },
    "recurrence": "one_time"
  }
}

Expire a credit grant

POST/v1/billing/credit_grants/{id}/expire

Expires a credit grant.

Path parameters

  • idstringRequired

    Unique identifier for the object.

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.credit_grant object.

POST /v1/billing/credit_grants/{id}/expire
curl -X POST https://api.knoxapi.com/v1/billing/credit_grants/obj_123/expire \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": {
    "monetary": {
      "currency": "currency",
      "value": 111972721
    },
    "type": "monetary"
  },
  "applicability_config": {
    "scope": {
      "price_type": "metered"
    }
  },
  "category": "paid",
  "created": 1028554472,
  "customer": {
    "created": 1028554472,
    "default_source": null,
    "description": null,
    "email": null,
    "id": "obj_123",
    "livemode": true,
    "object": "customer",
    "shipping": {}
  },
  "effective_at": null,
  "expires_at": null,
  "id": "obj_123",
  "livemode": true,
  "metadata": {
    "undefined": "metadata"
  },
  "name": null,
  "object": "billing.credit_grant",
  "test_clock": null,
  "updated": 234430277,
  "voided_at": null,
  "customer_account": null,
  "priority": 50
}

Void a credit grant

POST/v1/billing/credit_grants/{id}/void

Voids a credit grant.

Path parameters

  • idstringRequired

    Unique identifier for the object.

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.credit_grant object.

POST /v1/billing/credit_grants/{id}/void
curl -X POST https://api.knoxapi.com/v1/billing/credit_grants/obj_123/void \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": {
    "monetary": {
      "currency": "currency",
      "value": 111972721
    },
    "type": "monetary"
  },
  "applicability_config": {
    "scope": {
      "price_type": "metered"
    }
  },
  "category": "paid",
  "created": 1028554472,
  "customer": {
    "created": 1028554472,
    "default_source": null,
    "description": null,
    "email": null,
    "id": "obj_123",
    "livemode": true,
    "object": "customer",
    "shipping": {}
  },
  "effective_at": null,
  "expires_at": null,
  "id": "obj_123",
  "livemode": true,
  "metadata": {
    "undefined": "metadata"
  },
  "name": null,
  "object": "billing.credit_grant",
  "test_clock": null,
  "updated": 234430277,
  "voided_at": null,
  "customer_account": null,
  "priority": 50
}

Deactivate a feedback option

POST/v1/billing/feedback_options/{id}/deactivate

Deactivates a feedback option. Deactivated feedback options cannot be used in portal configurations.

Path parameters

  • idstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.feedback_option object.

POST /v1/billing/feedback_options/{id}/deactivate
curl -X POST https://api.knoxapi.com/v1/billing/feedback_options/obj_123/deactivate \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "object": "billing.feedback_option",
  "description": "description",
  "id": "obj_123",
  "livemode": true,
  "status": "active",
  "status_transitions": {
    "deactivated_at": null
  }
}

Deactivate a billing meter

POST/v1/billing/meters/{id}/deactivate

When a meter is deactivated, no more meter events will be accepted for this meter. You can’t attach a deactivated meter to a price.

Path parameters

  • idstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.meter object.

POST /v1/billing/meters/{id}/deactivate
curl -X POST https://api.knoxapi.com/v1/billing/meters/meter_123/deactivate \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "customer_mapping": {
    "event_payload_key": "customer",
    "type": "by_id"
  },
  "default_aggregation": {
    "formula": "sum"
  },
  "display_name": "test-meter",
  "event_name": "test-meter-event-name",
  "event_time_window": null,
  "id": "meter_123",
  "livemode": true,
  "object": "billing.meter",
  "status": "active",
  "status_transitions": {
    "deactivated_at": null
  },
  "updated": 1234567890,
  "value_settings": {
    "event_payload_key": "value"
  }
}

List billing meter event summaries

GET/v1/billing/meters/{id}/event_summaries

Retrieve a list of billing meter event summaries.

Path parameters

  • idstringRequired

    Unique identifier for the object.

Query parameters

  • customerstringRequired

    The customer for which to fetch event summaries.

  • end_timeintegerRequired

    The timestamp from when to stop aggregating meter events (exclusive). Must be aligned with minute boundaries.

  • start_timeintegerRequired

    The timestamp from when to start aggregating meter events (inclusive). Must be aligned with minute boundaries.

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

  • value_grouping_windowstring

    Specifies what granularity to use when generating event summaries. If not specified, a single event summary would be returned for the specified time range. For hourly granularity, start and end times must align with hour boundaries (e.g., 00:00, 01:00, ..., 23:00). For daily granularity, start and end times must align with UTC day boundaries (00:00 UTC).

    Possible values
    • day
    • hour

Returns

A list of billing.meter_event_summary objects.

GET /v1/billing/meters/{id}/event_summaries
curl -G https://api.knoxapi.com/v1/billing/meters/mtrusg_123/event_summaries \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode customer=cus_QXg1o8vcGmoR32 \
  --data-urlencode end_time=1234567890 \
  --data-urlencode start_time=1234567890
Response
{
  "object": "list",
  "url": "/v1/billing/meters",
  "has_more": false,
  "data": [
    {
      "aggregated_value": 25,
      "end_time": 1234567890,
      "id": "mtrusg_123",
      "livemode": false,
      "meter": "mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA",
      "object": "billing.meter_event_summary",
      "start_time": 1234567890
    }
  ]
}

Reactivate a billing meter

POST/v1/billing/meters/{id}/reactivate

When a meter is reactivated, events for this meter can be accepted and you can attach the meter to a price.

Path parameters

  • idstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The billing.meter object.

POST /v1/billing/meters/{id}/reactivate
curl -X POST https://api.knoxapi.com/v1/billing/meters/meter_123/reactivate \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "customer_mapping": {
    "event_payload_key": "customer",
    "type": "by_id"
  },
  "default_aggregation": {
    "formula": "sum"
  },
  "display_name": "test-meter",
  "event_name": "test-meter-event-name",
  "event_time_window": null,
  "id": "meter_123",
  "livemode": true,
  "object": "billing.meter",
  "status": "active",
  "status_transitions": {
    "deactivated_at": null
  },
  "updated": 1234567890,
  "value_settings": {
    "event_payload_key": "value"
  }
}

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.