API reference

Customers

This object represents a customer of your business. Use it to create recurring charges, save payment and contact information, and track payments that belong to the same customer.

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.

Base URL
https://api.knoxapi.com
Endpoints

Create a customer

POST/v1/customers

Creates a new customer object.

Body parameters

  • addressobject

    The customer's address. Learn about country-specific requirements for calculating tax.

    Show 6 child parameters
    • citystring
    • countrystring
    • line1string
    • line2string
    • postal_codestring
    • statestring
  • balanceinteger

    An integer amount in cents (or local equivalent) that represents the customer's current balance, which affect the customer's future invoices. A negative amount represents a credit that decreases the amount due on an invoice; a positive amount increases the amount due on an invoice.

  • business_namestring

    The customer's business name. This may be up to *150 characters*.

  • cash_balanceobject

    Balance information and default balance settings for this customer.

    Show 1 child parameter
    • settingsobject
      Show 1 child parameter
      • reconciliation_modestring
        Possible values
        • automatic
        • manual
        • merchant_default
  • descriptionstring

    An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.

  • emailstring

    Customer's email address. It's displayed alongside the customer in your dashboard and can be useful for searching and tracking. This may be up to *512 characters*.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • individual_namestring

    The customer's full name. This may be up to *150 characters*.

  • invoice_prefixstring

    The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.

  • invoice_settingsobject

    Default invoice settings for this customer.

    Show 4 child parameters
    • custom_fieldsarray of objects
      Show 2 child parameters
      • namestringRequired
      • valuestringRequired
    • default_payment_methodstring
    • footerstring
    • rendering_optionsobject
      Show 2 child parameters
      • amount_tax_displaystring
        Possible values
        • exclude_tax
        • include_inclusive_tax
      • templatestring
  • 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.

  • namestring

    The customer's full name or business name.

  • next_invoice_sequenceinteger

    The sequence to be used on the customer's next invoice. Defaults to 1.

  • payment_methodstring
  • phonestring

    The customer's phone number.

  • preferred_localesarray of strings

    Customer's preferred languages, ordered by preference.

  • shippingobject

    The customer's shipping information. Appears on invoices emailed to this customer.

    Show 3 child parameters
    • addressobjectRequired
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • namestringRequired
    • phonestring
  • sourcestring
  • taxobject

    Tax details about the customer.

    Show 2 child parameters
    • ip_addressstring
    • validate_locationstring
      Possible values
      • deferred
      • immediately
  • tax_exemptstring

    The customer's tax exemption. One of none, exempt, or reverse.

    Possible values
    • exempt
    • none
    • reverse
  • tax_id_dataarray of objects

    The customer's tax IDs.

    Show 2 child parameters
    • typestringRequired
      Possible values
      • ad_nrt
      • ae_trn
      • al_tin
      • am_tin
      • ao_tin
      • ar_cuit
      • au_abn
      • au_arn
      • aw_tin
      • az_tin
      • ba_tin
      • bb_tin
      • bd_bin
      • bf_ifu
      • bg_uic
      • bh_vat
      • and 101 more
    • valuestringRequired
  • test_clockstring

    ID of the test clock to attach to the customer.

Returns

The customer object.

POST /v1/customers
curl -X POST https://api.knoxapi.com/v1/customers \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "address": {
    "city": null,
    "country": null,
    "line1": null,
    "line2": null,
    "postal_code": null,
    "state": null
  },
  "balance": 0,
  "created": 1234567890,
  "currency": "usd",
  "default_source": null,
  "delinquent": false,
  "description": null,
  "discount": {
    "checkout_session": null,
    "customer": null,
    "end": null,
    "id": "obj_123",
    "invoice": null,
    "invoice_item": null,
    "object": "discount",
    "promotion_code": null,
    "start": 109757538,
    "subscription": null,
    "subscription_item": null,
    "source": {
      "coupon": null,
      "type": "coupon"
    },
    "customer_account": null
  },
  "email": null,
  "id": "cus_QXg1o8vcGmoR32",
  "invoice_prefix": "7FE1103",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null,
    "rendering_options": {
      "amount_tax_display": null,
      "template": null
    }
  },
  "livemode": false,
  "metadata": {},
  "name": null,
  "next_invoice_sequence": 1,
  "object": "customer",
  "phone": null,
  "preferred_locales": [],
  "shipping": {},
  "tax_exempt": "none",
  "test_clock": null
}

List all customers

GET/v1/customers

Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

Query parameters

  • createdobject | integer

    Only return customers that were created during the given date interval.

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

    A case-sensitive filter on the list based on the customer's email field. The value must be a string.

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

  • test_clockstring

    Provides a list of customers that are associated with the specified test clock. The response will not include customers with test clocks if this parameter is not set.

Returns

A list of customer objects.

GET /v1/customers
curl -G https://api.knoxapi.com/v1/customers \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "balance": 0,
      "created": 1234567890,
      "currency": "usd",
      "default_source": null,
      "delinquent": false,
      "description": null,
      "discount": {
        "checkout_session": null,
        "customer": null,
        "end": null,
        "id": "obj_123",
        "invoice": null,
        "invoice_item": null,
        "object": "discount",
        "promotion_code": null,
        "start": 109757538,
        "subscription": null,
        "subscription_item": null,
        "source": {
          "coupon": null,
          "type": "coupon"
        },
        "customer_account": null
      },
      "email": null,
      "id": "cus_QXg1o8vcGmoR32",
      "invoice_prefix": "7FE1103",
      "invoice_settings": {
        "custom_fields": null,
        "default_payment_method": null,
        "footer": null,
        "rendering_options": {
          "amount_tax_display": null,
          "template": null
        }
      },
      "livemode": false,
      "metadata": {},
      "name": null,
      "next_invoice_sequence": 1,
      "object": "customer",
      "phone": null,
      "preferred_locales": [],
      "shipping": {},
      "tax_exempt": "none",
      "test_clock": null
    }
  ]
}

Search customers

GET/v1/customers/search

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

Query parameters

  • querystringRequired

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

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

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

  • pagestring

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

Returns

A search result of customer objects.

GET /v1/customers/search
curl -G https://api.knoxapi.com/v1/customers/search \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode "query=metadata['order_id']:'6735'"
Response
{
  "object": "search_result",
  "url": "/v1/customers/search",
  "has_more": false,
  "data": [
    {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "balance": 0,
      "created": 1234567890,
      "currency": "usd",
      "default_source": null,
      "delinquent": false,
      "description": null,
      "discount": {
        "checkout_session": null,
        "customer": null,
        "end": null,
        "id": "obj_123",
        "invoice": null,
        "invoice_item": null,
        "object": "discount",
        "promotion_code": null,
        "start": 109757538,
        "subscription": null,
        "subscription_item": null,
        "source": {
          "coupon": null,
          "type": "coupon"
        },
        "customer_account": null
      },
      "email": null,
      "id": "cus_QXg1o8vcGmoR32",
      "invoice_prefix": "7FE1103",
      "invoice_settings": {
        "custom_fields": null,
        "default_payment_method": null,
        "footer": null,
        "rendering_options": {
          "amount_tax_display": null,
          "template": null
        }
      },
      "livemode": false,
      "metadata": {},
      "name": null,
      "next_invoice_sequence": 1,
      "object": "customer",
      "phone": null,
      "preferred_locales": [],
      "shipping": {},
      "tax_exempt": "none",
      "test_clock": null
    }
  ],
  "next_page": null
}

Update a customer

POST/v1/customers/{customer}

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided are left unchanged. For example, if you pass the source parameter, that becomes the customer’s active source (such as a card) to be used for all charges in the future. When you update a customer to a new valid card source by passing the source parameter: for each of the customer’s current subscriptions, if the subscription bills automatically and is in the past_due state, then the latest open invoice for the subscription with automatic collection enabled is retried. This retry doesn’t count as an automatic retry, and doesn’t affect the next regularly scheduled payment for the invoice. Changing the default_source for a customer doesn’t trigger this behavior. This request accepts mostly the same arguments as the customer creation call.

Path parameters

  • customerstringRequired

Body parameters

  • addressobject

    The customer's address. Learn about country-specific requirements for calculating tax.

    Show 6 child parameters
    • citystring
    • countrystring
    • line1string
    • line2string
    • postal_codestring
    • statestring
  • balanceinteger

    An integer amount in cents (or local equivalent) that represents the customer's current balance, which affect the customer's future invoices. A negative amount represents a credit that decreases the amount due on an invoice; a positive amount increases the amount due on an invoice.

  • bank_accountobject | string

    Either a token, like the ones returned by Stripe.js, or a dictionary containing a user's bank account details.

    Show 7 child parameters
    • account_numberstringRequired
    • countrystringRequired
    • account_holder_namestring
    • account_holder_typestring
      Possible values
      • company
      • individual
    • currencystring
    • objectstring
      Possible values
      • bank_account
    • routing_numberstring
  • business_namestring

    The customer's business name. This may be up to *150 characters*.

  • cardobject | string

    A token, like the ones returned by Stripe.js.

    Show 16 child parameters
    • exp_monthintegerRequired
    • exp_yearintegerRequired
    • numberstringRequired
    • address_citystring
    • address_countrystring
    • address_line1string
    • address_line2string
    • address_statestring
    • address_zipstring
    • cvcstring
    • encryptedstring
    • metadataobject
    • namestring
    • network_tokenobject
      Show 1 child parameter
      • numberstring
    • objectstring
      Possible values
      • card
    • swipe_datastring
  • cash_balanceobject

    Balance information and default balance settings for this customer.

    Show 1 child parameter
    • settingsobject
      Show 1 child parameter
      • reconciliation_modestring
        Possible values
        • automatic
        • manual
        • merchant_default
  • default_alipay_accountstring

    ID of Alipay account to make the customer's new default for invoice payments.

  • default_bank_accountstring

    ID of bank account to make the customer's new default for invoice payments.

  • default_cardstring

    ID of card to make the customer's new default for invoice payments.

  • default_sourcestring

    If you are using payment methods created via the PaymentMethods API, see the invoice_settings.default_payment_method parameter. Provide the ID of a payment source already attached to this customer to make it this customer's default payment source. If you want to add a new payment source and make it the default, see the source property.

  • descriptionstring

    An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.

  • emailstring

    Customer's email address. It's displayed alongside the customer in your dashboard and can be useful for searching and tracking. This may be up to *512 characters*.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • individual_namestring

    The customer's full name. This may be up to *150 characters*.

  • invoice_prefixstring

    The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.

  • invoice_settingsobject

    Default invoice settings for this customer.

    Show 4 child parameters
    • custom_fieldsarray of objects
      Show 2 child parameters
      • namestringRequired
      • valuestringRequired
    • default_payment_methodstring
    • footerstring
    • rendering_optionsobject
      Show 2 child parameters
      • amount_tax_displaystring
        Possible values
        • exclude_tax
        • include_inclusive_tax
      • templatestring
  • 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.

  • namestring

    The customer's full name or business name.

  • next_invoice_sequenceinteger

    The sequence to be used on the customer's next invoice. Defaults to 1.

  • phonestring

    The customer's phone number.

  • preferred_localesarray of strings

    Customer's preferred languages, ordered by preference.

  • shippingobject

    The customer's shipping information. Appears on invoices emailed to this customer.

    Show 3 child parameters
    • addressobjectRequired
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • namestringRequired
    • phonestring
  • sourcestring
  • taxobject

    Tax details about the customer.

    Show 2 child parameters
    • ip_addressstring
    • validate_locationstring
      Possible values
      • auto
      • deferred
      • immediately
  • tax_exemptstring

    The customer's tax exemption. One of none, exempt, or reverse.

    Possible values
    • exempt
    • none
    • reverse

Returns

The customer object.

POST /v1/customers/{customer}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "address": {
    "city": null,
    "country": null,
    "line1": null,
    "line2": null,
    "postal_code": null,
    "state": null
  },
  "balance": 0,
  "created": 1234567890,
  "currency": "usd",
  "default_source": null,
  "delinquent": false,
  "description": null,
  "discount": {
    "checkout_session": null,
    "customer": null,
    "end": null,
    "id": "obj_123",
    "invoice": null,
    "invoice_item": null,
    "object": "discount",
    "promotion_code": null,
    "start": 109757538,
    "subscription": null,
    "subscription_item": null,
    "source": {
      "coupon": null,
      "type": "coupon"
    },
    "customer_account": null
  },
  "email": null,
  "id": "cus_QXg1o8vcGmoR32",
  "invoice_prefix": "7FE1103",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null,
    "rendering_options": {
      "amount_tax_display": null,
      "template": null
    }
  },
  "livemode": false,
  "metadata": {},
  "name": null,
  "next_invoice_sequence": 1,
  "object": "customer",
  "phone": null,
  "preferred_locales": [],
  "shipping": {},
  "tax_exempt": "none",
  "test_clock": null
}

Retrieve a customer

GET/v1/customers/{customer}

Retrieves a Customer object.

Path parameters

  • customerstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The customer object.

GET /v1/customers/{customer}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "address": {
    "city": null,
    "country": null,
    "line1": null,
    "line2": null,
    "postal_code": null,
    "state": null
  },
  "balance": 0,
  "created": 1234567890,
  "currency": "usd",
  "default_source": null,
  "delinquent": false,
  "description": null,
  "discount": {
    "checkout_session": null,
    "customer": null,
    "end": null,
    "id": "obj_123",
    "invoice": null,
    "invoice_item": null,
    "object": "discount",
    "promotion_code": null,
    "start": 109757538,
    "subscription": null,
    "subscription_item": null,
    "source": {
      "coupon": null,
      "type": "coupon"
    },
    "customer_account": null
  },
  "email": null,
  "id": "cus_QXg1o8vcGmoR32",
  "invoice_prefix": "7FE1103",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null,
    "rendering_options": {
      "amount_tax_display": null,
      "template": null
    }
  },
  "livemode": false,
  "metadata": {},
  "name": null,
  "next_invoice_sequence": 1,
  "object": "customer",
  "phone": null,
  "preferred_locales": [],
  "shipping": {},
  "tax_exempt": "none",
  "test_clock": null
}

Delete a customer

DELETE/v1/customers/{customer}

Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.

Path parameters

  • customerstringRequired

Returns

The deleted_customer object.

DELETE /v1/customers/{customer}
curl -X DELETE https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "cus_QXg1o8vcGmoR32",
  "object": "customer"
}

Create a customer balance transaction

POST/v1/customers/{customer}/balance_transactions

Creates an immutable transaction that updates the customer’s credit balance.

Path parameters

  • customerstringRequired

Body parameters

  • amountintegerRequired

    The integer amount in **cents (or local equivalent)** to apply to the customer's credit balance.

  • currencystringRequired

    Three-letter ISO currency code, in lowercase. Must be a supported currency. Specifies the invoice_credit_balance that this transaction will apply to. If the customer's currency is not set, it will be updated to this value.

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users.

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

Returns

The customer_balance_transaction object.

POST /v1/customers/{customer}/balance_transactions
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/balance_transactions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d amount=-500 \
  -d currency=usd
Response
{
  "amount": -500,
  "created": 1234567890,
  "credit_note": null,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "description": null,
  "ending_balance": -500,
  "id": "cbtxn_1Pgc75B7WZ01zgkWgM0DfYYl",
  "invoice": null,
  "livemode": false,
  "metadata": null,
  "object": "customer_balance_transaction",
  "type": "adjustment",
  "checkout_session": null,
  "customer_account": null
}

List customer balance transactions

GET/v1/customers/{customer}/balance_transactions

Returns a list of transactions that updated the customer’s balances.

Path parameters

  • customerstringRequired

Query parameters

  • createdobject | integer

    Only return customer balance transactions that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • 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.

  • invoicestring

    Only return transactions that are related to the specified invoice.

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

GET /v1/customers/{customer}/balance_transactions
curl -G https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/balance_transactions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "amount": -500,
      "created": 1234567890,
      "credit_note": null,
      "currency": "usd",
      "customer": "cus_QXg1o8vcGmoR32",
      "description": null,
      "ending_balance": -500,
      "id": "cbtxn_1Pgc75B7WZ01zgkWgM0DfYYl",
      "invoice": null,
      "livemode": false,
      "metadata": null,
      "object": "customer_balance_transaction",
      "type": "adjustment",
      "checkout_session": null,
      "customer_account": null
    }
  ]
}

Create a card

POST/v1/customers/{customer}/bank_accounts

When you create a new credit card, you must specify a customer or recipient on which to create it. If the card’s owner has no default card, then the new card will become the default. However, if the owner already has a default, then it will not change. To change the default, you should update the customer to have a new default_source.

Path parameters

  • customerstringRequired

Body parameters

  • alipay_accountstring

    A token returned by Stripe.js representing the user’s Alipay account details.

  • bank_accountobject | string

    Either a token, like the ones returned by Stripe.js, or a dictionary containing a user's bank account details.

    Show 7 child parameters
    • account_numberstringRequired
    • countrystringRequired
    • account_holder_namestring
    • account_holder_typestring
      Possible values
      • company
      • individual
    • currencystring
    • objectstring
      Possible values
      • bank_account
    • routing_numberstring
  • cardobject | string

    A token, like the ones returned by Stripe.js.

    Show 16 child parameters
    • exp_monthintegerRequired
    • exp_yearintegerRequired
    • numberstringRequired
    • address_citystring
    • address_countrystring
    • address_line1string
    • address_line2string
    • address_statestring
    • address_zipstring
    • cvcstring
    • encryptedstring
    • metadataobject
    • namestring
    • network_tokenobject
      Show 1 child parameter
      • numberstring
    • objectstring
      Possible values
      • card
    • swipe_datastring
  • 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.

  • sourcestring

    Please refer to full documentation instead.

Returns

The payment_source object.

POST /v1/customers/{customer}/bank_accounts
curl -X POST https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/bank_accounts \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "business_profile": {
    "annual_revenue": {
      "amount": null,
      "currency": null,
      "fiscal_year_end": null
    },
    "estimated_worker_count": null,
    "mcc": null,
    "name": null,
    "product_description": null,
    "support_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "support_email": null,
    "support_phone": null,
    "support_url": null,
    "url": null,
    "minority_owned_business_designation": null
  },
  "business_type": null,
  "capabilities": {
    "card_payments": "active",
    "transfers": "active"
  },
  "charges_enabled": false,
  "controller": {
    "type": "account"
  },
  "country": "US",
  "created": 1721948512,
  "default_currency": "usd",
  "details_submitted": false,
  "email": "[email protected]",
  "external_accounts": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/accounts/acct_1PgafTB7WZ01zgkW/external_accounts"
  },
  "future_requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id": "acct_1PgafTB7WZ01zgkW",
  "metadata": {},
  "object": "account",
  "payouts_enabled": false,
  "requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "disabled_reason": "requirements.past_due",
    "errors": [],
    "eventually_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "past_due": [],
    "pending_verification": []
  },
  "settings": {
    "bacs_debit_payments": {
      "display_name": null,
      "service_user_number": null
    },
    "branding": {
      "icon": null,
      "logo": null,
      "primary_color": null,
      "secondary_color": null
    },
    "card_issuing": {
      "tos_acceptance": {
        "date": null,
        "ip": null
      }
    },
    "card_payments": {
      "decline_on": {
        "avs_failure": true,
        "cvc_failure": true
      },
      "statement_descriptor_prefix": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "dashboard": {
      "display_name": null,
      "timezone": "Etc/UTC"
    },
    "invoices": {
      "default_account_tax_ids": null,
      "hosted_payment_method_save": null
    },
    "payments": {
      "statement_descriptor": null,
      "statement_descriptor_kana": null,
      "statement_descriptor_kanji": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "payouts": {
      "debit_negative_balances": true,
      "schedule": {
        "delay_days": 2,
        "interval": "daily"
      },
      "statement_descriptor": null
    },
    "sepa_debit_payments": {}
  },
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "type": "standard"
}

List all bank accounts

GET/v1/customers/{customer}/bank_accounts

You can see a list of the bank accounts belonging to a Customer. Note that the 10 most recent sources are always available by default on the Customer. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional bank accounts.

Path parameters

  • customerstringRequired

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.

Returns

A list of bank_account objects.

GET /v1/customers/{customer}/bank_accounts
curl -G https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/bank_accounts \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "account_holder_name": "Jane Austen",
      "account_holder_type": "company",
      "account_type": null,
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "currency": "usd",
      "customer": null,
      "fingerprint": "AuoSJ18zsVWV9SPc",
      "id": "ba_1PgagAB7WZ01zgkWr3DySp2Q",
      "last4": "6789",
      "metadata": {},
      "object": "bank_account",
      "routing_number": "110000000",
      "status": "new"
    }
  ]
}

Create a card

POST/v1/customers/{customer}/cards

When you create a new credit card, you must specify a customer or recipient on which to create it. If the card’s owner has no default card, then the new card will become the default. However, if the owner already has a default, then it will not change. To change the default, you should update the customer to have a new default_source.

Path parameters

  • customerstringRequired

Body parameters

  • alipay_accountstring

    A token returned by Stripe.js representing the user’s Alipay account details.

  • bank_accountobject | string

    Either a token, like the ones returned by Stripe.js, or a dictionary containing a user's bank account details.

    Show 7 child parameters
    • account_numberstringRequired
    • countrystringRequired
    • account_holder_namestring
    • account_holder_typestring
      Possible values
      • company
      • individual
    • currencystring
    • objectstring
      Possible values
      • bank_account
    • routing_numberstring
  • cardobject | string

    A token, like the ones returned by Stripe.js.

    Show 16 child parameters
    • exp_monthintegerRequired
    • exp_yearintegerRequired
    • numberstringRequired
    • address_citystring
    • address_countrystring
    • address_line1string
    • address_line2string
    • address_statestring
    • address_zipstring
    • cvcstring
    • encryptedstring
    • metadataobject
    • namestring
    • network_tokenobject
      Show 1 child parameter
      • numberstring
    • objectstring
      Possible values
      • card
    • swipe_datastring
  • 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.

  • sourcestring

    Please refer to full documentation instead.

Returns

The payment_source object.

POST /v1/customers/{customer}/cards
curl -X POST https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/cards \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "business_profile": {
    "annual_revenue": {
      "amount": null,
      "currency": null,
      "fiscal_year_end": null
    },
    "estimated_worker_count": null,
    "mcc": null,
    "name": null,
    "product_description": null,
    "support_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "support_email": null,
    "support_phone": null,
    "support_url": null,
    "url": null,
    "minority_owned_business_designation": null
  },
  "business_type": null,
  "capabilities": {
    "card_payments": "active",
    "transfers": "active"
  },
  "charges_enabled": false,
  "controller": {
    "type": "account"
  },
  "country": "US",
  "created": 1721948512,
  "default_currency": "usd",
  "details_submitted": false,
  "email": "[email protected]",
  "external_accounts": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/accounts/acct_1PgafTB7WZ01zgkW/external_accounts"
  },
  "future_requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id": "acct_1PgafTB7WZ01zgkW",
  "metadata": {},
  "object": "account",
  "payouts_enabled": false,
  "requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "disabled_reason": "requirements.past_due",
    "errors": [],
    "eventually_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "past_due": [],
    "pending_verification": []
  },
  "settings": {
    "bacs_debit_payments": {
      "display_name": null,
      "service_user_number": null
    },
    "branding": {
      "icon": null,
      "logo": null,
      "primary_color": null,
      "secondary_color": null
    },
    "card_issuing": {
      "tos_acceptance": {
        "date": null,
        "ip": null
      }
    },
    "card_payments": {
      "decline_on": {
        "avs_failure": true,
        "cvc_failure": true
      },
      "statement_descriptor_prefix": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "dashboard": {
      "display_name": null,
      "timezone": "Etc/UTC"
    },
    "invoices": {
      "default_account_tax_ids": null,
      "hosted_payment_method_save": null
    },
    "payments": {
      "statement_descriptor": null,
      "statement_descriptor_kana": null,
      "statement_descriptor_kanji": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "payouts": {
      "debit_negative_balances": true,
      "schedule": {
        "delay_days": 2,
        "interval": "daily"
      },
      "statement_descriptor": null
    },
    "sepa_debit_payments": {}
  },
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "type": "standard"
}

List all cards

GET/v1/customers/{customer}/cards

You can see a list of the cards belonging to a customer. Note that the 10 most recent sources are always available on the Customer object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional cards.

Path parameters

  • customerstringRequired

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.

Returns

A list of card objects.

GET /v1/customers/{customer}/cards
curl -G https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/cards \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "customer": null,
      "cvc_check": "pass",
      "dynamic_last4": null,
      "exp_month": 8,
      "exp_year": 2030,
      "fingerprint": "AOB934RVNwzk6xtn",
      "funding": "credit",
      "id": "card_1PgaftB7WZ01zgkWm3waTcFp",
      "last4": "4242",
      "metadata": {},
      "name": "Jenny Rosen",
      "object": "card",
      "tokenization_method": null,
      "regulated_status": null
    }
  ]
}

Update a cash balance's settings

POST/v1/customers/{customer}/cash_balance

Changes the settings on a customer’s cash balance.

Path parameters

  • customerstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • settingsobject

    A hash of settings for this cash balance.

    Show 1 child parameter
    • reconciliation_modestring
      Possible values
      • automatic
      • manual
      • merchant_default

Returns

The cash_balance object.

POST /v1/customers/{customer}/cash_balance
curl -X POST https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/cash_balance \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "available": {
    "eur": 10000
  },
  "customer": "cus_QXg1o8vcGmoR32",
  "livemode": false,
  "object": "cash_balance",
  "settings": {
    "reconciliation_mode": "automatic",
    "using_merchant_default": true
  },
  "customer_account": null
}

Retrieve a cash balance

GET/v1/customers/{customer}/cash_balance

Retrieves a customer’s cash balance.

Path parameters

  • customerstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The cash_balance object.

GET /v1/customers/{customer}/cash_balance
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/cash_balance \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "available": {
    "eur": 10000
  },
  "customer": "cus_QXg1o8vcGmoR32",
  "livemode": false,
  "object": "cash_balance",
  "settings": {
    "reconciliation_mode": "automatic",
    "using_merchant_default": true
  },
  "customer_account": null
}

List cash balance transactions

GET/v1/customers/{customer}/cash_balance_transactions

Returns a list of transactions that modified the customer’s cash balance.

Path parameters

  • customerstringRequired

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.

Returns

A list of customer_cash_balance_transaction objects.

GET /v1/customers/{customer}/cash_balance_transactions
curl -G https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/cash_balance_transactions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "created": 1234567890,
      "currency": "eur",
      "customer": "cus_QXg1o8vcGmoR32",
      "ending_balance": 10000,
      "funded": {
        "bank_transfer": {
          "eu_bank_transfer": {
            "bic": "BANKDEAAXXX",
            "iban_last4": "7089",
            "sender_name": "Sample Business GmbH"
          },
          "reference": "Payment for Invoice 7FE1103-155",
          "type": "eu_bank_transfer"
        }
      },
      "id": "ccsbtxn_1Pgc75B7WZ01zgkWzdJj4ufI",
      "livemode": false,
      "net_amount": 5000,
      "object": "customer_cash_balance_transaction",
      "type": "funded",
      "customer_account": null
    }
  ]
}

GET /v1/customers/{customer}/discount

GET/v1/customers/{customer}/discount

Path parameters

  • customerstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The discount object.

GET /v1/customers/{customer}/discount
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/discount \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "checkout_session": null,
  "customer": "cus_QXg1o8vcGmoR32",
  "end": 1234567890,
  "id": "di_1Pgc6rB7WZ01zgkW7Al8Fal9",
  "invoice": null,
  "invoice_item": null,
  "object": "discount",
  "promotion_code": null,
  "start": 1234567890,
  "subscription": null,
  "subscription_item": null,
  "source": {
    "coupon": null,
    "type": "coupon"
  },
  "customer_account": null
}

Delete a customer discount

DELETE/v1/customers/{customer}/discount

Removes the currently applied discount on a customer.

Path parameters

  • customerstringRequired

Returns

The deleted_discount object.

DELETE /v1/customers/{customer}/discount
curl -X DELETE https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/discount \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "",
  "object": "discount",
  "start": 1234567890,
  "checkout_session": null,
  "customer": null,
  "invoice": null,
  "invoice_item": null,
  "promotion_code": null,
  "subscription": null,
  "subscription_item": null,
  "source": {
    "coupon": null,
    "type": "coupon"
  },
  "customer_account": null
}

Create or retrieve funding instructions for a customer cash balance

POST/v1/customers/{customer}/funding_instructions

Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new funding instructions will be created. If funding instructions have already been created for a given customer, the same funding instructions will be retrieved. In other words, we will return the same funding instructions each time.

Path parameters

  • customerstringRequired

Body parameters

  • bank_transferobjectRequired

    Additional parameters for bank_transfer funding types

    Show 3 child parameters
    • typestringRequired
      Possible values
      • eu_bank_transfer
      • gb_bank_transfer
      • jp_bank_transfer
      • mx_bank_transfer
      • us_bank_transfer
    • eu_bank_transferobject
      Show 1 child parameter
      • countrystringRequired
    • requested_address_typesarray of strings
  • currencystringRequired

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

  • funding_typestringRequired

    The funding_type to get the instructions for.

    Possible values
    • bank_transfer
  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The funding_instructions object.

POST /v1/customers/{customer}/funding_instructions
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/funding_instructions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "bank_transfer[type]=eu_bank_transfer" \
  -d currency=usd \
  -d funding_type=bank_transfer
Response
{
  "bank_transfer": {
    "country": "US",
    "financial_addresses": [
      {
        "supported_networks": [
          "ach",
          "domestic_wire_us"
        ],
        "type": "aba"
      }
    ],
    "type": "eu_bank_transfer"
  },
  "currency": "usd",
  "funding_type": "bank_transfer",
  "livemode": false,
  "object": "funding_instructions"
}

List a Customer's PaymentMethods

GET/v1/customers/{customer}/payment_methods

Returns a list of PaymentMethods for a given Customer

Path parameters

  • customerstringRequired

Query parameters

  • allow_redisplaystring

    This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow.

    Possible values
    • always
    • limited
    • unspecified
  • 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.

  • typestring

    An optional filter on the list, based on the object type field. Without the filter, the list includes all current and future payment method types. If your integration expects only one type of payment method in the response, make sure to provide a type value in the request.

    Possible values
    • acss_debit
    • affirm
    • afterpay_clearpay
    • alipay
    • alma
    • amazon_pay
    • au_becs_debit
    • bacs_debit
    • bancontact
    • billie
    • bizum
    • blik
    • boleto
    • card
    • cashapp
    • crypto
    • and 39 more

Returns

A list of payment_method objects.

GET /v1/customers/{customer}/payment_methods
curl -G https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/payment_methods \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "allow_redisplay": "unspecified",
      "billing_details": {
        "address": {
          "city": "San Francisco",
          "country": "US",
          "line1": "1234 Fake Street",
          "line2": null,
          "postal_code": "94102",
          "state": "CA"
        },
        "email": "[email protected]",
        "name": null,
        "phone": "+15555555555",
        "tax_id": null
      },
      "card": {
        "brand": "visa",
        "checks": {
          "address_line1_check": null,
          "address_postal_code_check": null,
          "cvc_check": "pass"
        },
        "country": "US",
        "display_brand": "visa",
        "exp_month": 8,
        "exp_year": 2030,
        "fingerprint": "AOB934RVNwzk6xtn",
        "funding": "credit",
        "generated_from": {
          "charge": null,
          "payment_method_details": {
            "type": "type"
          },
          "setup_attempt": null
        },
        "last4": "4242",
        "networks": {
          "available": [
            "visa"
          ],
          "preferred": null
        },
        "three_d_secure_usage": {
          "supported": true
        },
        "wallet": {
          "dynamic_last4": null,
          "type": "link"
        },
        "regulated_status": null
      },
      "created": 1234567890,
      "customer": null,
      "id": "pm_1Pgc75B7WZ01zgkWlHVgdEGJ",
      "livemode": false,
      "metadata": {
        "order_id": "123456789"
      },
      "object": "payment_method",
      "type": "card",
      "customer_account": null
    }
  ]
}

Create a card

POST/v1/customers/{customer}/sources

When you create a new credit card, you must specify a customer or recipient on which to create it. If the card’s owner has no default card, then the new card will become the default. However, if the owner already has a default, then it will not change. To change the default, you should update the customer to have a new default_source.

Path parameters

  • customerstringRequired

Body parameters

  • alipay_accountstring

    A token returned by Stripe.js representing the user’s Alipay account details.

  • bank_accountobject | string

    Either a token, like the ones returned by Stripe.js, or a dictionary containing a user's bank account details.

    Show 7 child parameters
    • account_numberstringRequired
    • countrystringRequired
    • account_holder_namestring
    • account_holder_typestring
      Possible values
      • company
      • individual
    • currencystring
    • objectstring
      Possible values
      • bank_account
    • routing_numberstring
  • cardobject | string

    A token, like the ones returned by Stripe.js.

    Show 16 child parameters
    • exp_monthintegerRequired
    • exp_yearintegerRequired
    • numberstringRequired
    • address_citystring
    • address_countrystring
    • address_line1string
    • address_line2string
    • address_statestring
    • address_zipstring
    • cvcstring
    • encryptedstring
    • metadataobject
    • namestring
    • network_tokenobject
      Show 1 child parameter
      • numberstring
    • objectstring
      Possible values
      • card
    • swipe_datastring
  • 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.

  • sourcestring

    Please refer to full documentation instead.

Returns

The payment_source object.

POST /v1/customers/{customer}/sources
curl -X POST https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/sources \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "business_profile": {
    "annual_revenue": {
      "amount": null,
      "currency": null,
      "fiscal_year_end": null
    },
    "estimated_worker_count": null,
    "mcc": null,
    "name": null,
    "product_description": null,
    "support_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "support_email": null,
    "support_phone": null,
    "support_url": null,
    "url": null,
    "minority_owned_business_designation": null
  },
  "business_type": null,
  "capabilities": {
    "card_payments": "active",
    "transfers": "active"
  },
  "charges_enabled": false,
  "controller": {
    "type": "account"
  },
  "country": "US",
  "created": 1721948512,
  "default_currency": "usd",
  "details_submitted": false,
  "email": "[email protected]",
  "external_accounts": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/accounts/acct_1PgafTB7WZ01zgkW/external_accounts"
  },
  "future_requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id": "acct_1PgafTB7WZ01zgkW",
  "metadata": {},
  "object": "account",
  "payouts_enabled": false,
  "requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "disabled_reason": "requirements.past_due",
    "errors": [],
    "eventually_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "past_due": [],
    "pending_verification": []
  },
  "settings": {
    "bacs_debit_payments": {
      "display_name": null,
      "service_user_number": null
    },
    "branding": {
      "icon": null,
      "logo": null,
      "primary_color": null,
      "secondary_color": null
    },
    "card_issuing": {
      "tos_acceptance": {
        "date": null,
        "ip": null
      }
    },
    "card_payments": {
      "decline_on": {
        "avs_failure": true,
        "cvc_failure": true
      },
      "statement_descriptor_prefix": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "dashboard": {
      "display_name": null,
      "timezone": "Etc/UTC"
    },
    "invoices": {
      "default_account_tax_ids": null,
      "hosted_payment_method_save": null
    },
    "payments": {
      "statement_descriptor": null,
      "statement_descriptor_kana": null,
      "statement_descriptor_kanji": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "payouts": {
      "debit_negative_balances": true,
      "schedule": {
        "delay_days": 2,
        "interval": "daily"
      },
      "statement_descriptor": null
    },
    "sepa_debit_payments": {}
  },
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "type": "standard"
}

GET /v1/customers/{customer}/sources

GET/v1/customers/{customer}/sources

List sources for a specified customer.

Path parameters

  • customerstringRequired

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.

  • objectstring

    Filter sources according to a particular object type.

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

GET /v1/customers/{customer}/sources
curl -G https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/sources \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "account_holder_name": "Jane Austen",
      "account_holder_type": "company",
      "account_type": null,
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "currency": "usd",
      "customer": null,
      "fingerprint": "AuoSJ18zsVWV9SPc",
      "id": "ba_1PgagAB7WZ01zgkWr3DySp2Q",
      "last4": "6789",
      "metadata": {},
      "object": "bank_account",
      "routing_number": "110000000",
      "status": "new"
    }
  ]
}

Create a subscription

POST/v1/customers/{customer}/subscriptions

Creates a new subscription on an existing customer.

Path parameters

  • customerstringRequired

Body parameters

  • add_invoice_itemsarray of objects

    A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.

    Show 8 child parameters
    • discountableboolean
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • metadataobject
    • periodobject
      Show 2 child parameters
    • pricestring
    • price_dataobject
      Show 5 child parameters
      • currencystringRequired
      • productstringRequired
      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • tax_ratesarray of strings
  • application_fee_percentnumber

    A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees documentation.

  • automatic_taxobject

    Automatic tax settings for this subscription.

    Show 2 child parameters
    • enabledbooleanRequired
    • liabilityobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • backdate_start_dateinteger

    A past timestamp to backdate the subscription's start date to. If set, the first invoice will contain line items for the timespan between the start date and the current time. Can be combined with trials and the billing cycle anchor.

  • billing_cycle_anchorinteger

    A future timestamp in UTC format to anchor the subscription's billing cycle. The anchor is the reference point that aligns future billing cycle dates. It sets the day of week for week intervals, the day of month for month and year intervals, and the month of year for year intervals.

  • billing_thresholdsobject

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

    Show 2 child parameters
    • amount_gteinteger
    • reset_billing_cycle_anchorboolean
  • cancel_atinteger | string

    A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using proration_behavior. If set during a future period, this will always cause a proration for that period.

    Possible values
    • max_billed_until
    • max_period_end
    • min_period_end
  • cancel_at_period_endboolean

    Indicate whether this subscription should cancel at the end of the current period (current_period_end). Defaults to false.

  • collection_methodstring

    Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically.

    Possible values
    • charge_automatically
    • send_invoice
  • currencystring

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

  • days_until_dueinteger

    Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where collection_method is set to send_invoice.

  • default_payment_methodstring

    ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.

  • default_sourcestring

    ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If default_payment_method is also set, default_payment_method will take precedence. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.

  • default_tax_ratesarray of strings

    The tax rates that will apply to any subscription item that does not have tax_rates set. Invoices created will have their default_tax_rates populated from the subscription.

  • discountsarray of objects

    The coupons to redeem into discounts for the subscription. If not specified or empty, inherits the discount from the subscription's customer.

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

    Specifies which fields in the response should be expanded.

  • invoice_settingsobject

    All invoices will be billed using the specified settings.

    Show 5 child parameters
    • account_tax_idsarray of strings
    • custom_fieldsarray of objects
      Show 2 child parameters
      • namestringRequired
      • valuestringRequired
    • descriptionstring
    • footerstring
    • issuerobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • itemsarray of objects

    A list of up to 20 subscription items, each with an attached price.

    Show 7 child parameters
    • billing_thresholdsobject
      Show 1 child parameter
      • usage_gteintegerRequired
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • metadataobject
    • pricestring
    • price_dataobject
      Show 6 child parameters
      • currencystringRequired
      • productstringRequired
      • recurringobjectRequired

        Child parameters are listed in the OpenAPI document.

      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • tax_ratesarray of strings
  • 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 the first invoice when payment is required and collection_method=charge_automatically. Subscriptions with collection_method=send_invoice are automatically activated regardless of the first Invoice status.

    Possible values
    • allow_incomplete
    • default_incomplete
    • error_if_incomplete
    • pending_if_incomplete
  • payment_settingsobject

    Payment settings to pass to invoices created by the subscription.

    Show 3 child parameters
    • payment_method_optionsobject
      Show 11 child parameters
    • payment_method_typesarray of strings
    • save_default_payment_methodstring
      Possible values
      • off
      • on_subscription
  • pending_invoice_item_intervalobject

    Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling Create an invoice for the given subscription at the specified interval.

    Show 2 child parameters
    • intervalstringRequired
      Possible values
      • day
      • month
      • week
      • year
    • interval_countinteger
  • proration_behaviorstring

    Determines how to handle prorations resulting from the billing_cycle_anchor. If no value is passed, the default is create_prorations.

    Possible values
    • always_invoice
    • create_prorations
    • none
  • transfer_dataobject

    If specified, the funds from the subscription's invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges.

    Show 2 child parameters
    • destinationstringRequired
    • amount_percentnumber
  • trial_endstring | integer

    Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately. Can be at most two years from billing_cycle_anchor. See Using trial periods on subscriptions to learn more.

    Possible values
    • now
  • trial_from_planboolean

    Indicates if a plan's trial_period_days should be applied to the subscription. Setting trial_end per subscription is preferred, and this defaults to false. Setting this flag to true together with trial_end is not allowed. See Using trial periods on subscriptions to learn more.

  • trial_period_daysinteger

    Integer representing the number of trial period days before the customer is charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. See Using trial periods on subscriptions to learn more.

  • trial_settingsobject

    Settings related to subscription trials.

    Show 1 child parameter
    • end_behaviorobjectRequired
      Show 1 child parameter
      • missing_payment_methodstringRequired
        Possible values
        • cancel
        • create_invoice
        • pause

Returns

The subscription object.

POST /v1/customers/{customer}/subscriptions
curl -X POST https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/subscriptions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "disabled_reason": null
  },
  "billing_cycle_anchor": 1234567890,
  "billing_cycle_anchor_config": {
    "day_of_month": 1361669285,
    "hour": null,
    "minute": null,
    "month": null,
    "second": null
  },
  "cancel_at": 1234567890,
  "canceled_at": 1234567890,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null,
    "feedback_option": null
  },
  "collection_method": "charge_automatically",
  "created": 1234567890,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "ended_at": 1234567890,
  "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
  "invoice_settings": {
    "account_tax_ids": null,
    "issuer": {
      "type": "self"
    },
    "custom_fields": null,
    "description": null,
    "footer": null
  },
  "items": {
    "data": [
      {
        "created": 1721954054,
        "discounts": [],
        "id": "si_QXhVnC2h0Jczwc",
        "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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
        "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
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
  },
  "latest_invoice": null,
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": 1234567890,
  "object": "subscription",
  "on_behalf_of": null,
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resumes_at": null
  },
  "payment_settings": {
    "payment_method_options": {
      "acss_debit": {},
      "bancontact": {
        "preferred_language": "fr"
      },
      "card": {
        "network": null,
        "request_three_d_secure": null
      },
      "customer_balance": {
        "funding_type": null
      },
      "konbini": {},
      "sepa_debit": {},
      "us_bank_account": {},
      "payto": {},
      "pix": {},
      "upi": {},
      "billie": {}
    },
    "payment_method_types": null,
    "save_default_payment_method": null
  },
  "pending_invoice_item_interval": {
    "interval": "month",
    "interval_count": 797691627
  },
  "pending_setup_intent": null,
  "pending_update": {
    "billing_cycle_anchor": null,
    "discount": {
      "checkout_session": null,
      "customer": null,
      "end": null,
      "id": "obj_123",
      "invoice": null,
      "invoice_item": null,
      "object": "discount",
      "promotion_code": null,
      "start": 109757538,
      "subscription": null,
      "subscription_item": null,
      "source": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    },
    "discounts": [],
    "expires_at": 833811170,
    "subscription_items": null,
    "trial_end": null,
    "trial_from_plan": null,
    "metadata": null,
    "cancel_at_period_end": null
  },
  "schedule": null,
  "start_date": 1234567890,
  "status": "active",
  "test_clock": null,
  "transfer_data": {
    "amount_percent": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "trial_end": 1234567890,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": 1234567890,
  "cancel_at_period_end": true,
  "billing_thresholds": {
    "amount_gte": null,
    "reset_billing_cycle_anchor": null
  },
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null,
  "managed_payments": {
    "enabled": true
  },
  "billing_schedules": [
    {
      "applies_to": null,
      "bill_until": {
        "computed_timestamp": 2082605468,
        "duration": {
          "interval": "month",
          "interval_count": null
        },
        "timestamp": null,
        "type": "duration"
      },
      "key": "key"
    }
  ]
}

List active subscriptions

GET/v1/customers/{customer}/subscriptions

You can see a list of the customer’s active subscriptions. Note that the 10 most recent active subscriptions are always available by default on the customer object. If you need more than those 10, you can use the limit and starting_after parameters to page through additional subscriptions.

Path parameters

  • customerstringRequired

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.

Returns

A list of subscription objects.

GET /v1/customers/{customer}/subscriptions
curl -G https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/subscriptions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "application": null,
      "application_fee_percent": null,
      "automatic_tax": {
        "enabled": false,
        "liability": {
          "type": "account"
        },
        "disabled_reason": null
      },
      "billing_cycle_anchor": 1234567890,
      "billing_cycle_anchor_config": {
        "day_of_month": 1361669285,
        "hour": null,
        "minute": null,
        "month": null,
        "second": null
      },
      "cancel_at": 1234567890,
      "canceled_at": 1234567890,
      "cancellation_details": {
        "comment": null,
        "feedback": null,
        "reason": null,
        "feedback_option": null
      },
      "collection_method": "charge_automatically",
      "created": 1234567890,
      "currency": "usd",
      "customer": "cus_QXg1o8vcGmoR32",
      "days_until_due": null,
      "default_payment_method": null,
      "default_source": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "ended_at": 1234567890,
      "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
      "invoice_settings": {
        "account_tax_ids": null,
        "issuer": {
          "type": "self"
        },
        "custom_fields": null,
        "description": null,
        "footer": null
      },
      "items": {
        "data": [
          {
            "created": 1721954054,
            "discounts": [],
            "id": "si_QXhVnC2h0Jczwc",
            "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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
            "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
            }
          }
        ],
        "has_more": false,
        "object": "list",
        "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
      },
      "latest_invoice": null,
      "livemode": false,
      "metadata": {},
      "next_pending_invoice_item_invoice": 1234567890,
      "object": "subscription",
      "on_behalf_of": null,
      "pause_collection": {
        "behavior": "mark_uncollectible",
        "resumes_at": null
      },
      "payment_settings": {
        "payment_method_options": {
          "acss_debit": {},
          "bancontact": {
            "preferred_language": "fr"
          },
          "card": {
            "network": null,
            "request_three_d_secure": null
          },
          "customer_balance": {
            "funding_type": null
          },
          "konbini": {},
          "sepa_debit": {},
          "us_bank_account": {},
          "payto": {},
          "pix": {},
          "upi": {},
          "billie": {}
        },
        "payment_method_types": null,
        "save_default_payment_method": null
      },
      "pending_invoice_item_interval": {
        "interval": "month",
        "interval_count": 797691627
      },
      "pending_setup_intent": null,
      "pending_update": {
        "billing_cycle_anchor": null,
        "discount": {
          "checkout_session": null,
          "customer": null,
          "end": null,
          "id": "obj_123",
          "invoice": null,
          "invoice_item": null,
          "object": "discount",
          "promotion_code": null,
          "start": 109757538,
          "subscription": null,
          "subscription_item": null,
          "source": {
            "coupon": null,
            "type": "coupon"
          },
          "customer_account": null
        },
        "discounts": [],
        "expires_at": 833811170,
        "subscription_items": null,
        "trial_end": null,
        "trial_from_plan": null,
        "metadata": null,
        "cancel_at_period_end": null
      },
      "schedule": null,
      "start_date": 1234567890,
      "status": "active",
      "test_clock": null,
      "transfer_data": {
        "amount_percent": null,
        "destination": {
          "id": "obj_123",
          "object": "account"
        }
      },
      "trial_end": 1234567890,
      "trial_settings": {
        "end_behavior": {
          "missing_payment_method": "create_invoice"
        }
      },
      "trial_start": 1234567890,
      "cancel_at_period_end": true,
      "billing_thresholds": {
        "amount_gte": null,
        "reset_billing_cycle_anchor": null
      },
      "billing_mode": {
        "type": "classic",
        "flexible": {}
      },
      "customer_account": null,
      "managed_payments": {
        "enabled": true
      },
      "billing_schedules": [
        {
          "applies_to": null,
          "bill_until": {
            "computed_timestamp": 2082605468,
            "duration": {
              "interval": "month",
              "interval_count": null
            },
            "timestamp": null,
            "type": "duration"
          },
          "key": "key"
        }
      ]
    }
  ]
}

Create a Customer tax ID

POST/v1/customers/{customer}/tax_ids

Creates a new tax_id object for a customer.

Path parameters

  • customerstringRequired

Body parameters

  • typestringRequired

    Type of the tax ID, one of ad_nrt, ae_trn, al_tin, am_tin, ao_tin, ar_cuit, au_abn, au_arn, aw_tin, az_tin, ba_tin, bb_tin, bd_bin, bf_ifu, bg_uic, bh_vat, bj_ifu, bo_tin, br_cnpj, br_cpf, bs_tin, by_tin, ca_bn, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, ca_qst, cd_nif, ch_uid, ch_vat, cl_tin, cm_niu, cn_tin, co_nit, cr_tin, cv_nif, de_stn, do_rcn, ec_ruc, eg_tin, es_cif, et_tin, eu_oss_vat, eu_vat, fo_vat, gb_vat, ge_vat, gi_tin, gn_nif, hk_br, hr_oib, hu_tin, ic_nif, id_npwp, il_vat, in_gst, is_vat, it_cf, jp_cn, jp_rn, jp_trn, ke_pin, kg_tin, kh_tin, kr_brn, kz_bin, la_tin, li_uid, li_vat, lk_vat, ma_vat, md_vat, me_pib, mk_vat, mr_nif, mx_rfc, my_frp, my_itn, my_sst, ng_tin, no_vat, no_voec, np_pan, nz_gst, om_vat, pe_ruc, ph_tin, pl_nip, py_ruc, ro_tin, rs_pib, ru_inn, ru_kpp, sa_vat, sg_gst, sg_uen, si_tin, sn_ninea, sr_fin, sv_nit, th_vat, tj_tin, tr_tin, tw_vat, tz_vat, ua_vat, ug_tin, us_ein, uy_ruc, uz_tin, uz_vat, ve_rif, vn_tin, za_vat, zm_tin, or zw_tin

    Possible values
    • ad_nrt
    • ae_trn
    • al_tin
    • am_tin
    • ao_tin
    • ar_cuit
    • au_abn
    • au_arn
    • aw_tin
    • az_tin
    • ba_tin
    • bb_tin
    • bd_bin
    • bf_ifu
    • bg_uic
    • bh_vat
    • and 101 more
  • valuestringRequired

    Value of the tax ID.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The tax_id object.

POST /v1/customers/{customer}/tax_ids
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/tax_ids \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d type=eu_vat \
  -d value=DE123456789
Response
{
  "country": "DE",
  "created": 1234567890,
  "customer": "cus_QXg1o8vcGmoR32",
  "id": "txi_1Pgc6sB7WZ01zgkWXkvC78jZ",
  "livemode": false,
  "object": "tax_id",
  "owner": {
    "customer": "cus_QXg1o8vcGmoR32",
    "type": "customer",
    "customer_account": null
  },
  "type": "eu_vat",
  "value": "DE123456789",
  "verification": {
    "status": "pending",
    "verified_address": null,
    "verified_name": null
  },
  "customer_account": null
}

List all Customer tax IDs

GET/v1/customers/{customer}/tax_ids

Returns a list of tax IDs for a customer.

Path parameters

  • customerstringRequired

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.

Returns

A list of tax_id objects.

GET /v1/customers/{customer}/tax_ids
curl -G https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/tax_ids \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "country": "DE",
      "created": 1234567890,
      "customer": "cus_QXg1o8vcGmoR32",
      "id": "txi_1Pgc6sB7WZ01zgkWXkvC78jZ",
      "livemode": false,
      "object": "tax_id",
      "owner": {
        "customer": "cus_QXg1o8vcGmoR32",
        "type": "customer",
        "customer_account": null
      },
      "type": "eu_vat",
      "value": "DE123456789",
      "verification": {
        "status": "pending",
        "verified_address": null,
        "verified_name": null
      },
      "customer_account": null
    }
  ]
}

Update a customer credit balance transaction

POST/v1/customers/{customer}/balance_transactions/{transaction}

Most credit balance transaction fields are immutable, but you may update its description and metadata.

Path parameters

  • customerstringRequired
  • transactionstringRequired

Body parameters

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users.

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

Returns

The customer_balance_transaction object.

POST /v1/customers/{customer}/balance_transactions/{transaction}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/balance_transactions/cbtxn_1Pgc75B7WZ01zgkWgM0DfYYl \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "amount": -500,
  "created": 1234567890,
  "credit_note": null,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "description": null,
  "ending_balance": -500,
  "id": "cbtxn_1Pgc75B7WZ01zgkWgM0DfYYl",
  "invoice": null,
  "livemode": false,
  "metadata": null,
  "object": "customer_balance_transaction",
  "type": "adjustment",
  "checkout_session": null,
  "customer_account": null
}

Retrieve a customer balance transaction

GET/v1/customers/{customer}/balance_transactions/{transaction}

Retrieves a specific customer balance transaction that updated the customer’s balances.

Path parameters

  • customerstringRequired
  • transactionstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The customer_balance_transaction object.

GET /v1/customers/{customer}/balance_transactions/{transaction}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/balance_transactions/cbtxn_1Pgc75B7WZ01zgkWgM0DfYYl \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": -500,
  "created": 1234567890,
  "credit_note": null,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "description": null,
  "ending_balance": -500,
  "id": "cbtxn_1Pgc75B7WZ01zgkWgM0DfYYl",
  "invoice": null,
  "livemode": false,
  "metadata": null,
  "object": "customer_balance_transaction",
  "type": "adjustment",
  "checkout_session": null,
  "customer_account": null
}

Update a card

POST/v1/customers/{customer}/bank_accounts/{id}

Update a specified source for a given customer.

Path parameters

  • customerstringRequired
  • idstringRequired

Body parameters

  • account_holder_namestring

    The name of the person or business that owns the bank account.

  • account_holder_typestring

    The type of entity that holds the account. This can be either individual or company.

    Possible values
    • company
    • individual
  • address_citystring

    City/District/Suburb/Town/Village.

  • address_countrystring

    Billing address country, if provided when creating card.

  • address_line1string

    Address line 1 (Street address/PO Box/Company name).

  • address_line2string

    Address line 2 (Apartment/Suite/Unit/Building).

  • address_statestring

    State/County/Province/Region.

  • address_zipstring

    ZIP or postal code.

  • exp_monthstring

    Two digit number representing the card’s expiration month.

  • exp_yearstring

    Four digit number representing the card’s expiration year.

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

  • namestring

    Cardholder name.

  • ownerobject
    Show 4 child parameters
    • addressobject
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • emailstring
    • namestring
    • phonestring

Returns

The card object.

POST /v1/customers/{customer}/bank_accounts/{id}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/bank_accounts/card_1PgaftB7WZ01zgkWm3waTcFp \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "pass",
  "dynamic_last4": null,
  "exp_month": 8,
  "exp_year": 2030,
  "fingerprint": "AOB934RVNwzk6xtn",
  "funding": "credit",
  "id": "card_1PgaftB7WZ01zgkWm3waTcFp",
  "last4": "4242",
  "metadata": {},
  "name": "Jenny Rosen",
  "object": "card",
  "tokenization_method": null,
  "regulated_status": null
}

Retrieve a bank account

GET/v1/customers/{customer}/bank_accounts/{id}

By default, you can see the 10 most recent sources stored on a Customer directly on the object, but you can also retrieve details about a specific bank account stored on the Stripe account.

Path parameters

  • customerstringRequired
  • idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The bank_account object.

GET /v1/customers/{customer}/bank_accounts/{id}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/bank_accounts/ba_1PgagAB7WZ01zgkWr3DySp2Q \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "account_holder_name": "Jane Austen",
  "account_holder_type": "company",
  "account_type": null,
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "customer": null,
  "fingerprint": "AuoSJ18zsVWV9SPc",
  "id": "ba_1PgagAB7WZ01zgkWr3DySp2Q",
  "last4": "6789",
  "metadata": {},
  "object": "bank_account",
  "routing_number": "110000000",
  "status": "new"
}

Delete a customer source

DELETE/v1/customers/{customer}/bank_accounts/{id}

Delete a specified source for a given customer.

Path parameters

  • customerstringRequired
  • idstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The payment_source object.

DELETE /v1/customers/{customer}/bank_accounts/{id}
curl -X DELETE https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/bank_accounts/acct_1PgafTB7WZ01zgkW \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "business_profile": {
    "annual_revenue": {
      "amount": null,
      "currency": null,
      "fiscal_year_end": null
    },
    "estimated_worker_count": null,
    "mcc": null,
    "name": null,
    "product_description": null,
    "support_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "support_email": null,
    "support_phone": null,
    "support_url": null,
    "url": null,
    "minority_owned_business_designation": null
  },
  "business_type": null,
  "capabilities": {
    "card_payments": "active",
    "transfers": "active"
  },
  "charges_enabled": false,
  "controller": {
    "type": "account"
  },
  "country": "US",
  "created": 1721948512,
  "default_currency": "usd",
  "details_submitted": false,
  "email": "[email protected]",
  "external_accounts": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/accounts/acct_1PgafTB7WZ01zgkW/external_accounts"
  },
  "future_requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id": "acct_1PgafTB7WZ01zgkW",
  "metadata": {},
  "object": "account",
  "payouts_enabled": false,
  "requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "disabled_reason": "requirements.past_due",
    "errors": [],
    "eventually_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "past_due": [],
    "pending_verification": []
  },
  "settings": {
    "bacs_debit_payments": {
      "display_name": null,
      "service_user_number": null
    },
    "branding": {
      "icon": null,
      "logo": null,
      "primary_color": null,
      "secondary_color": null
    },
    "card_issuing": {
      "tos_acceptance": {
        "date": null,
        "ip": null
      }
    },
    "card_payments": {
      "decline_on": {
        "avs_failure": true,
        "cvc_failure": true
      },
      "statement_descriptor_prefix": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "dashboard": {
      "display_name": null,
      "timezone": "Etc/UTC"
    },
    "invoices": {
      "default_account_tax_ids": null,
      "hosted_payment_method_save": null
    },
    "payments": {
      "statement_descriptor": null,
      "statement_descriptor_kana": null,
      "statement_descriptor_kanji": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "payouts": {
      "debit_negative_balances": true,
      "schedule": {
        "delay_days": 2,
        "interval": "daily"
      },
      "statement_descriptor": null
    },
    "sepa_debit_payments": {}
  },
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "type": "standard"
}

Update a card

POST/v1/customers/{customer}/cards/{id}

Update a specified source for a given customer.

Path parameters

  • customerstringRequired
  • idstringRequired

Body parameters

  • account_holder_namestring

    The name of the person or business that owns the bank account.

  • account_holder_typestring

    The type of entity that holds the account. This can be either individual or company.

    Possible values
    • company
    • individual
  • address_citystring

    City/District/Suburb/Town/Village.

  • address_countrystring

    Billing address country, if provided when creating card.

  • address_line1string

    Address line 1 (Street address/PO Box/Company name).

  • address_line2string

    Address line 2 (Apartment/Suite/Unit/Building).

  • address_statestring

    State/County/Province/Region.

  • address_zipstring

    ZIP or postal code.

  • exp_monthstring

    Two digit number representing the card’s expiration month.

  • exp_yearstring

    Four digit number representing the card’s expiration year.

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

  • namestring

    Cardholder name.

  • ownerobject
    Show 4 child parameters
    • addressobject
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • emailstring
    • namestring
    • phonestring

Returns

The card object.

POST /v1/customers/{customer}/cards/{id}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/cards/card_1PgaftB7WZ01zgkWm3waTcFp \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "pass",
  "dynamic_last4": null,
  "exp_month": 8,
  "exp_year": 2030,
  "fingerprint": "AOB934RVNwzk6xtn",
  "funding": "credit",
  "id": "card_1PgaftB7WZ01zgkWm3waTcFp",
  "last4": "4242",
  "metadata": {},
  "name": "Jenny Rosen",
  "object": "card",
  "tokenization_method": null,
  "regulated_status": null
}

Retrieve a card

GET/v1/customers/{customer}/cards/{id}

You can always see the 10 most recent cards directly on a customer; this method lets you retrieve details about a specific card stored on the customer.

Path parameters

  • customerstringRequired
  • idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The card object.

GET /v1/customers/{customer}/cards/{id}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/cards/card_1PgaftB7WZ01zgkWm3waTcFp \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "pass",
  "dynamic_last4": null,
  "exp_month": 8,
  "exp_year": 2030,
  "fingerprint": "AOB934RVNwzk6xtn",
  "funding": "credit",
  "id": "card_1PgaftB7WZ01zgkWm3waTcFp",
  "last4": "4242",
  "metadata": {},
  "name": "Jenny Rosen",
  "object": "card",
  "tokenization_method": null,
  "regulated_status": null
}

Delete a customer source

DELETE/v1/customers/{customer}/cards/{id}

Delete a specified source for a given customer.

Path parameters

  • customerstringRequired
  • idstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The payment_source object.

DELETE /v1/customers/{customer}/cards/{id}
curl -X DELETE https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/cards/acct_1PgafTB7WZ01zgkW \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "business_profile": {
    "annual_revenue": {
      "amount": null,
      "currency": null,
      "fiscal_year_end": null
    },
    "estimated_worker_count": null,
    "mcc": null,
    "name": null,
    "product_description": null,
    "support_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "support_email": null,
    "support_phone": null,
    "support_url": null,
    "url": null,
    "minority_owned_business_designation": null
  },
  "business_type": null,
  "capabilities": {
    "card_payments": "active",
    "transfers": "active"
  },
  "charges_enabled": false,
  "controller": {
    "type": "account"
  },
  "country": "US",
  "created": 1721948512,
  "default_currency": "usd",
  "details_submitted": false,
  "email": "[email protected]",
  "external_accounts": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/accounts/acct_1PgafTB7WZ01zgkW/external_accounts"
  },
  "future_requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id": "acct_1PgafTB7WZ01zgkW",
  "metadata": {},
  "object": "account",
  "payouts_enabled": false,
  "requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "disabled_reason": "requirements.past_due",
    "errors": [],
    "eventually_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "past_due": [],
    "pending_verification": []
  },
  "settings": {
    "bacs_debit_payments": {
      "display_name": null,
      "service_user_number": null
    },
    "branding": {
      "icon": null,
      "logo": null,
      "primary_color": null,
      "secondary_color": null
    },
    "card_issuing": {
      "tos_acceptance": {
        "date": null,
        "ip": null
      }
    },
    "card_payments": {
      "decline_on": {
        "avs_failure": true,
        "cvc_failure": true
      },
      "statement_descriptor_prefix": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "dashboard": {
      "display_name": null,
      "timezone": "Etc/UTC"
    },
    "invoices": {
      "default_account_tax_ids": null,
      "hosted_payment_method_save": null
    },
    "payments": {
      "statement_descriptor": null,
      "statement_descriptor_kana": null,
      "statement_descriptor_kanji": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "payouts": {
      "debit_negative_balances": true,
      "schedule": {
        "delay_days": 2,
        "interval": "daily"
      },
      "statement_descriptor": null
    },
    "sepa_debit_payments": {}
  },
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "type": "standard"
}

Retrieve a cash balance transaction

GET/v1/customers/{customer}/cash_balance_transactions/{transaction}

Retrieves a specific cash balance transaction, which updated the customer’s cash balance.

Path parameters

  • customerstringRequired
  • transactionstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The customer_cash_balance_transaction object.

GET /v1/customers/{customer}/cash_balance_transactions/{transaction}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/cash_balance_transactions/ccsbtxn_1Pgc75B7WZ01zgkWzdJj4ufI \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "currency": "eur",
  "customer": "cus_QXg1o8vcGmoR32",
  "ending_balance": 10000,
  "funded": {
    "bank_transfer": {
      "eu_bank_transfer": {
        "bic": "BANKDEAAXXX",
        "iban_last4": "7089",
        "sender_name": "Sample Business GmbH"
      },
      "reference": "Payment for Invoice 7FE1103-155",
      "type": "eu_bank_transfer"
    }
  },
  "id": "ccsbtxn_1Pgc75B7WZ01zgkWzdJj4ufI",
  "livemode": false,
  "net_amount": 5000,
  "object": "customer_cash_balance_transaction",
  "type": "funded",
  "customer_account": null
}

Retrieve a Customer's PaymentMethod

GET/v1/customers/{customer}/payment_methods/{payment_method}

Retrieves a PaymentMethod object for a given Customer.

Path parameters

  • customerstringRequired
  • payment_methodstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The payment_method object.

GET /v1/customers/{customer}/payment_methods/{payment_method}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/payment_methods/pm_1Pgc75B7WZ01zgkWlHVgdEGJ \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "allow_redisplay": "unspecified",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Fake Street",
      "line2": null,
      "postal_code": "94102",
      "state": "CA"
    },
    "email": "[email protected]",
    "name": null,
    "phone": "+15555555555",
    "tax_id": null
  },
  "card": {
    "brand": "visa",
    "checks": {
      "address_line1_check": null,
      "address_postal_code_check": null,
      "cvc_check": "pass"
    },
    "country": "US",
    "display_brand": "visa",
    "exp_month": 8,
    "exp_year": 2030,
    "fingerprint": "AOB934RVNwzk6xtn",
    "funding": "credit",
    "generated_from": {
      "charge": null,
      "payment_method_details": {
        "type": "type"
      },
      "setup_attempt": null
    },
    "last4": "4242",
    "networks": {
      "available": [
        "visa"
      ],
      "preferred": null
    },
    "three_d_secure_usage": {
      "supported": true
    },
    "wallet": {
      "dynamic_last4": null,
      "type": "link"
    },
    "regulated_status": null
  },
  "created": 1234567890,
  "customer": null,
  "id": "pm_1Pgc75B7WZ01zgkWlHVgdEGJ",
  "livemode": false,
  "metadata": {
    "order_id": "123456789"
  },
  "object": "payment_method",
  "type": "card",
  "customer_account": null
}

Update a card

POST/v1/customers/{customer}/sources/{id}

Update a specified source for a given customer.

Path parameters

  • customerstringRequired
  • idstringRequired

Body parameters

  • account_holder_namestring

    The name of the person or business that owns the bank account.

  • account_holder_typestring

    The type of entity that holds the account. This can be either individual or company.

    Possible values
    • company
    • individual
  • address_citystring

    City/District/Suburb/Town/Village.

  • address_countrystring

    Billing address country, if provided when creating card.

  • address_line1string

    Address line 1 (Street address/PO Box/Company name).

  • address_line2string

    Address line 2 (Apartment/Suite/Unit/Building).

  • address_statestring

    State/County/Province/Region.

  • address_zipstring

    ZIP or postal code.

  • exp_monthstring

    Two digit number representing the card’s expiration month.

  • exp_yearstring

    Four digit number representing the card’s expiration year.

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

  • namestring

    Cardholder name.

  • ownerobject
    Show 4 child parameters
    • addressobject
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • emailstring
    • namestring
    • phonestring

Returns

The card object.

POST /v1/customers/{customer}/sources/{id}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/sources/card_1PgaftB7WZ01zgkWm3waTcFp \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "pass",
  "dynamic_last4": null,
  "exp_month": 8,
  "exp_year": 2030,
  "fingerprint": "AOB934RVNwzk6xtn",
  "funding": "credit",
  "id": "card_1PgaftB7WZ01zgkWm3waTcFp",
  "last4": "4242",
  "metadata": {},
  "name": "Jenny Rosen",
  "object": "card",
  "tokenization_method": null,
  "regulated_status": null
}

GET /v1/customers/{customer}/sources/{id}

GET/v1/customers/{customer}/sources/{id}

Retrieve a specified source for a given customer.

Path parameters

  • customerstringRequired
  • idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The payment_source object.

GET /v1/customers/{customer}/sources/{id}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/sources/acct_1PgafTB7WZ01zgkW \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "business_profile": {
    "annual_revenue": {
      "amount": null,
      "currency": null,
      "fiscal_year_end": null
    },
    "estimated_worker_count": null,
    "mcc": null,
    "name": null,
    "product_description": null,
    "support_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "support_email": null,
    "support_phone": null,
    "support_url": null,
    "url": null,
    "minority_owned_business_designation": null
  },
  "business_type": null,
  "capabilities": {
    "card_payments": "active",
    "transfers": "active"
  },
  "charges_enabled": false,
  "controller": {
    "type": "account"
  },
  "country": "US",
  "created": 1721948512,
  "default_currency": "usd",
  "details_submitted": false,
  "email": "[email protected]",
  "external_accounts": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/accounts/acct_1PgafTB7WZ01zgkW/external_accounts"
  },
  "future_requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id": "acct_1PgafTB7WZ01zgkW",
  "metadata": {},
  "object": "account",
  "payouts_enabled": false,
  "requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "disabled_reason": "requirements.past_due",
    "errors": [],
    "eventually_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "past_due": [],
    "pending_verification": []
  },
  "settings": {
    "bacs_debit_payments": {
      "display_name": null,
      "service_user_number": null
    },
    "branding": {
      "icon": null,
      "logo": null,
      "primary_color": null,
      "secondary_color": null
    },
    "card_issuing": {
      "tos_acceptance": {
        "date": null,
        "ip": null
      }
    },
    "card_payments": {
      "decline_on": {
        "avs_failure": true,
        "cvc_failure": true
      },
      "statement_descriptor_prefix": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "dashboard": {
      "display_name": null,
      "timezone": "Etc/UTC"
    },
    "invoices": {
      "default_account_tax_ids": null,
      "hosted_payment_method_save": null
    },
    "payments": {
      "statement_descriptor": null,
      "statement_descriptor_kana": null,
      "statement_descriptor_kanji": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "payouts": {
      "debit_negative_balances": true,
      "schedule": {
        "delay_days": 2,
        "interval": "daily"
      },
      "statement_descriptor": null
    },
    "sepa_debit_payments": {}
  },
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "type": "standard"
}

Delete a customer source

DELETE/v1/customers/{customer}/sources/{id}

Delete a specified source for a given customer.

Path parameters

  • customerstringRequired
  • idstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The payment_source object.

DELETE /v1/customers/{customer}/sources/{id}
curl -X DELETE https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/sources/acct_1PgafTB7WZ01zgkW \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "business_profile": {
    "annual_revenue": {
      "amount": null,
      "currency": null,
      "fiscal_year_end": null
    },
    "estimated_worker_count": null,
    "mcc": null,
    "name": null,
    "product_description": null,
    "support_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "support_email": null,
    "support_phone": null,
    "support_url": null,
    "url": null,
    "minority_owned_business_designation": null
  },
  "business_type": null,
  "capabilities": {
    "card_payments": "active",
    "transfers": "active"
  },
  "charges_enabled": false,
  "controller": {
    "type": "account"
  },
  "country": "US",
  "created": 1721948512,
  "default_currency": "usd",
  "details_submitted": false,
  "email": "[email protected]",
  "external_accounts": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/accounts/acct_1PgafTB7WZ01zgkW/external_accounts"
  },
  "future_requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id": "acct_1PgafTB7WZ01zgkW",
  "metadata": {},
  "object": "account",
  "payouts_enabled": false,
  "requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "disabled_reason": "requirements.past_due",
    "errors": [],
    "eventually_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "past_due": [],
    "pending_verification": []
  },
  "settings": {
    "bacs_debit_payments": {
      "display_name": null,
      "service_user_number": null
    },
    "branding": {
      "icon": null,
      "logo": null,
      "primary_color": null,
      "secondary_color": null
    },
    "card_issuing": {
      "tos_acceptance": {
        "date": null,
        "ip": null
      }
    },
    "card_payments": {
      "decline_on": {
        "avs_failure": true,
        "cvc_failure": true
      },
      "statement_descriptor_prefix": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "dashboard": {
      "display_name": null,
      "timezone": "Etc/UTC"
    },
    "invoices": {
      "default_account_tax_ids": null,
      "hosted_payment_method_save": null
    },
    "payments": {
      "statement_descriptor": null,
      "statement_descriptor_kana": null,
      "statement_descriptor_kanji": null,
      "statement_descriptor_prefix_kana": null,
      "statement_descriptor_prefix_kanji": null
    },
    "payouts": {
      "debit_negative_balances": true,
      "schedule": {
        "delay_days": 2,
        "interval": "daily"
      },
      "statement_descriptor": null
    },
    "sepa_debit_payments": {}
  },
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "type": "standard"
}

Update a subscription on a customer

POST/v1/customers/{customer}/subscriptions/{subscription_exposed_id}

Updates an existing subscription on a customer to match the specified parameters. When changing plans or quantities, we will optionally prorate the price we charge next month to make up for any price changes. To preview how the proration will be calculated, use the upcoming invoice endpoint.

Path parameters

  • customerstringRequired
  • subscription_exposed_idstringRequired

Body parameters

  • add_invoice_itemsarray of objects

    A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.

    Show 8 child parameters
    • discountableboolean
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • metadataobject
    • periodobject
      Show 2 child parameters
    • pricestring
    • price_dataobject
      Show 5 child parameters
      • currencystringRequired
      • productstringRequired
      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • tax_ratesarray of strings
  • application_fee_percentnumber

    A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees documentation.

  • automatic_taxobject

    Automatic tax settings for this subscription. We recommend you only include this parameter when the existing value is being changed.

    Show 2 child parameters
    • enabledbooleanRequired
    • liabilityobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • billing_cycle_anchorstring

    Either now or unchanged. Setting the value to now resets the subscription's billing cycle anchor to the current time. For more information, see the billing cycle documentation.

    Possible values
    • now
    • unchanged
  • billing_thresholdsobject

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

    Show 2 child parameters
    • amount_gteinteger
    • reset_billing_cycle_anchorboolean
  • cancel_atinteger | string

    A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using proration_behavior. If set during a future period, this will always cause a proration for that period.

    Possible values
    • max_billed_until
    • max_period_end
    • min_period_end
  • cancel_at_period_endboolean

    Indicate whether this subscription should cancel at the end of the current period (current_period_end).

  • cancellation_detailsobject

    Details about why this subscription was cancelled

    Show 3 child parameters
    • commentstring
    • feedbackstring
      Possible values
      • customer_service
      • low_quality
      • missing_features
      • other
      • switched_service
      • too_complex
      • too_expensive
      • unused
    • feedback_optionstring
  • collection_methodstring

    Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically.

    Possible values
    • charge_automatically
    • send_invoice
  • days_until_dueinteger

    Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where collection_method is set to send_invoice.

  • default_payment_methodstring

    ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.

  • default_sourcestring

    ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If default_payment_method is also set, default_payment_method will take precedence. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.

  • default_tax_ratesarray of strings

    The tax rates that will apply to any subscription item that does not have tax_rates set. Invoices created will have their default_tax_rates populated from the subscription. Pass an empty string to remove previously-defined tax rates.

  • discountsarray of objects

    The coupons to redeem into discounts for the subscription. A populated array overwrites the existing discounts on the subscription. If not specified or empty array, it leaves the subscription's discounts unchanged. If empty string, it clears the subscription's discounts.

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

    Specifies which fields in the response should be expanded.

  • invoice_settingsobject

    All invoices will be billed using the specified settings.

    Show 5 child parameters
    • account_tax_idsarray of strings
    • custom_fieldsarray of objects
      Show 2 child parameters
      • namestringRequired
      • valuestringRequired
    • descriptionstring
    • footerstring
    • issuerobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • itemsarray of objects

    A list of up to 20 subscription items, each with an attached price.

    Show 10 child parameters
    • billing_thresholdsobject
      Show 1 child parameter
      • usage_gteintegerRequired
    • clear_usageboolean
    • deletedboolean
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • idstring
    • metadataobject
    • pricestring
    • price_dataobject
      Show 6 child parameters
      • currencystringRequired
      • productstringRequired
      • recurringobjectRequired

        Child parameters are listed in the OpenAPI document.

      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • tax_ratesarray of strings
  • 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).

  • pause_collectionobject

    If specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to paused. Learn more about pausing collection.

    Show 2 child parameters
    • behaviorstringRequired
      Possible values
      • keep_as_draft
      • mark_uncollectible
      • void
    • resumes_atinteger
  • 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
  • payment_settingsobject

    Payment settings to pass to invoices created by the subscription.

    Show 3 child parameters
    • payment_method_optionsobject
      Show 11 child parameters
    • payment_method_typesarray of strings
    • save_default_payment_methodstring
      Possible values
      • off
      • on_subscription
  • pending_invoice_item_intervalobject

    Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling Create an invoice for the given subscription at the specified interval.

    Show 2 child parameters
    • intervalstringRequired
      Possible values
      • day
      • month
      • week
      • year
    • interval_countinteger
  • 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, prorations will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same prorations that were previewed with the create preview endpoint. proration_date can also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations.

  • transfer_dataobject

    If specified, the funds from the subscription's invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges. This will be unset if you POST an empty value.

    Show 2 child parameters
    • destinationstringRequired
    • amount_percentnumber
  • trial_endstring | integer

    Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately. Can be at most two years from billing_cycle_anchor.

    Possible values
    • now
  • trial_from_planboolean

    Indicates if a plan's trial_period_days should be applied to the subscription. Setting trial_end per subscription is preferred, and this defaults to false. Setting this flag to true together with trial_end is not allowed. See Using trial periods on subscriptions to learn more.

  • trial_settingsobject

    Settings related to subscription trials.

    Show 1 child parameter
    • end_behaviorobjectRequired
      Show 1 child parameter
      • missing_payment_methodstringRequired
        Possible values
        • cancel
        • create_invoice
        • pause

Returns

The subscription object.

POST /v1/customers/{customer}/subscriptions/{subscription_exposed_id}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/subscriptions/subscription_exposed_id_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "application": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "disabled_reason": null
  },
  "billing_cycle_anchor": 1234567890,
  "billing_cycle_anchor_config": {
    "day_of_month": 1361669285,
    "hour": null,
    "minute": null,
    "month": null,
    "second": null
  },
  "cancel_at": 1234567890,
  "canceled_at": 1234567890,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null,
    "feedback_option": null
  },
  "collection_method": "charge_automatically",
  "created": 1234567890,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "ended_at": 1234567890,
  "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
  "invoice_settings": {
    "account_tax_ids": null,
    "issuer": {
      "type": "self"
    },
    "custom_fields": null,
    "description": null,
    "footer": null
  },
  "items": {
    "data": [
      {
        "created": 1721954054,
        "discounts": [],
        "id": "si_QXhVnC2h0Jczwc",
        "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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
        "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
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
  },
  "latest_invoice": null,
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": 1234567890,
  "object": "subscription",
  "on_behalf_of": null,
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resumes_at": null
  },
  "payment_settings": {
    "payment_method_options": {
      "acss_debit": {},
      "bancontact": {
        "preferred_language": "fr"
      },
      "card": {
        "network": null,
        "request_three_d_secure": null
      },
      "customer_balance": {
        "funding_type": null
      },
      "konbini": {},
      "sepa_debit": {},
      "us_bank_account": {},
      "payto": {},
      "pix": {},
      "upi": {},
      "billie": {}
    },
    "payment_method_types": null,
    "save_default_payment_method": null
  },
  "pending_invoice_item_interval": {
    "interval": "month",
    "interval_count": 797691627
  },
  "pending_setup_intent": null,
  "pending_update": {
    "billing_cycle_anchor": null,
    "discount": {
      "checkout_session": null,
      "customer": null,
      "end": null,
      "id": "obj_123",
      "invoice": null,
      "invoice_item": null,
      "object": "discount",
      "promotion_code": null,
      "start": 109757538,
      "subscription": null,
      "subscription_item": null,
      "source": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    },
    "discounts": [],
    "expires_at": 833811170,
    "subscription_items": null,
    "trial_end": null,
    "trial_from_plan": null,
    "metadata": null,
    "cancel_at_period_end": null
  },
  "schedule": null,
  "start_date": 1234567890,
  "status": "active",
  "test_clock": null,
  "transfer_data": {
    "amount_percent": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "trial_end": 1234567890,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": 1234567890,
  "cancel_at_period_end": true,
  "billing_thresholds": {
    "amount_gte": null,
    "reset_billing_cycle_anchor": null
  },
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null,
  "managed_payments": {
    "enabled": true
  },
  "billing_schedules": [
    {
      "applies_to": null,
      "bill_until": {
        "computed_timestamp": 2082605468,
        "duration": {
          "interval": "month",
          "interval_count": null
        },
        "timestamp": null,
        "type": "duration"
      },
      "key": "key"
    }
  ]
}

Retrieve a subscription

GET/v1/customers/{customer}/subscriptions/{subscription_exposed_id}

Retrieves the subscription with the given ID.

Path parameters

  • customerstringRequired
  • subscription_exposed_idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The subscription object.

GET /v1/customers/{customer}/subscriptions/{subscription_exposed_id}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/subscriptions/subscription_exposed_id_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "disabled_reason": null
  },
  "billing_cycle_anchor": 1234567890,
  "billing_cycle_anchor_config": {
    "day_of_month": 1361669285,
    "hour": null,
    "minute": null,
    "month": null,
    "second": null
  },
  "cancel_at": 1234567890,
  "canceled_at": 1234567890,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null,
    "feedback_option": null
  },
  "collection_method": "charge_automatically",
  "created": 1234567890,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "ended_at": 1234567890,
  "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
  "invoice_settings": {
    "account_tax_ids": null,
    "issuer": {
      "type": "self"
    },
    "custom_fields": null,
    "description": null,
    "footer": null
  },
  "items": {
    "data": [
      {
        "created": 1721954054,
        "discounts": [],
        "id": "si_QXhVnC2h0Jczwc",
        "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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
        "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
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
  },
  "latest_invoice": null,
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": 1234567890,
  "object": "subscription",
  "on_behalf_of": null,
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resumes_at": null
  },
  "payment_settings": {
    "payment_method_options": {
      "acss_debit": {},
      "bancontact": {
        "preferred_language": "fr"
      },
      "card": {
        "network": null,
        "request_three_d_secure": null
      },
      "customer_balance": {
        "funding_type": null
      },
      "konbini": {},
      "sepa_debit": {},
      "us_bank_account": {},
      "payto": {},
      "pix": {},
      "upi": {},
      "billie": {}
    },
    "payment_method_types": null,
    "save_default_payment_method": null
  },
  "pending_invoice_item_interval": {
    "interval": "month",
    "interval_count": 797691627
  },
  "pending_setup_intent": null,
  "pending_update": {
    "billing_cycle_anchor": null,
    "discount": {
      "checkout_session": null,
      "customer": null,
      "end": null,
      "id": "obj_123",
      "invoice": null,
      "invoice_item": null,
      "object": "discount",
      "promotion_code": null,
      "start": 109757538,
      "subscription": null,
      "subscription_item": null,
      "source": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    },
    "discounts": [],
    "expires_at": 833811170,
    "subscription_items": null,
    "trial_end": null,
    "trial_from_plan": null,
    "metadata": null,
    "cancel_at_period_end": null
  },
  "schedule": null,
  "start_date": 1234567890,
  "status": "active",
  "test_clock": null,
  "transfer_data": {
    "amount_percent": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "trial_end": 1234567890,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": 1234567890,
  "cancel_at_period_end": true,
  "billing_thresholds": {
    "amount_gte": null,
    "reset_billing_cycle_anchor": null
  },
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null,
  "managed_payments": {
    "enabled": true
  },
  "billing_schedules": [
    {
      "applies_to": null,
      "bill_until": {
        "computed_timestamp": 2082605468,
        "duration": {
          "interval": "month",
          "interval_count": null
        },
        "timestamp": null,
        "type": "duration"
      },
      "key": "key"
    }
  ]
}

Cancel a subscription

DELETE/v1/customers/{customer}/subscriptions/{subscription_exposed_id}

Cancels a customer’s subscription. If you set the at_period_end parameter to true, the subscription will remain active until the end of the period, at which point it will be canceled and not renewed. Otherwise, with the default false value, the subscription is terminated immediately. In either case, the customer will not be charged again for the subscription. Note, however, that any pending invoice items that you’ve created will still be charged for at the end of the period, unless manually deleted. If you’ve set the subscription to cancel at the end of the period, any pending prorations will also be left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations will be removed. By default, upon subscription cancellation, Stripe will stop automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.

Path parameters

  • customerstringRequired
  • subscription_exposed_idstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • invoice_nowboolean

    Can be set to true if at_period_end is not set to true. Will generate a final invoice that invoices for any un-invoiced metered usage and new/pending proration invoice items.

  • prorateboolean

    Can be set to true if at_period_end is not set to true. Will generate a proration invoice item that credits remaining unused time until the subscription period end.

Returns

The subscription object.

DELETE /v1/customers/{customer}/subscriptions/{subscription_exposed_id}
curl -X DELETE https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/subscriptions/subscription_exposed_id_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "disabled_reason": null
  },
  "billing_cycle_anchor": 1234567890,
  "billing_cycle_anchor_config": {
    "day_of_month": 1361669285,
    "hour": null,
    "minute": null,
    "month": null,
    "second": null
  },
  "cancel_at": 1234567890,
  "canceled_at": 1234567890,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null,
    "feedback_option": null
  },
  "collection_method": "charge_automatically",
  "created": 1234567890,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "ended_at": 1234567890,
  "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
  "invoice_settings": {
    "account_tax_ids": null,
    "issuer": {
      "type": "self"
    },
    "custom_fields": null,
    "description": null,
    "footer": null
  },
  "items": {
    "data": [
      {
        "created": 1721954054,
        "discounts": [],
        "id": "si_QXhVnC2h0Jczwc",
        "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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
        "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
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
  },
  "latest_invoice": null,
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": 1234567890,
  "object": "subscription",
  "on_behalf_of": null,
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resumes_at": null
  },
  "payment_settings": {
    "payment_method_options": {
      "acss_debit": {},
      "bancontact": {
        "preferred_language": "fr"
      },
      "card": {
        "network": null,
        "request_three_d_secure": null
      },
      "customer_balance": {
        "funding_type": null
      },
      "konbini": {},
      "sepa_debit": {},
      "us_bank_account": {},
      "payto": {},
      "pix": {},
      "upi": {},
      "billie": {}
    },
    "payment_method_types": null,
    "save_default_payment_method": null
  },
  "pending_invoice_item_interval": {
    "interval": "month",
    "interval_count": 797691627
  },
  "pending_setup_intent": null,
  "pending_update": {
    "billing_cycle_anchor": null,
    "discount": {
      "checkout_session": null,
      "customer": null,
      "end": null,
      "id": "obj_123",
      "invoice": null,
      "invoice_item": null,
      "object": "discount",
      "promotion_code": null,
      "start": 109757538,
      "subscription": null,
      "subscription_item": null,
      "source": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    },
    "discounts": [],
    "expires_at": 833811170,
    "subscription_items": null,
    "trial_end": null,
    "trial_from_plan": null,
    "metadata": null,
    "cancel_at_period_end": null
  },
  "schedule": null,
  "start_date": 1234567890,
  "status": "active",
  "test_clock": null,
  "transfer_data": {
    "amount_percent": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "trial_end": 1234567890,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": 1234567890,
  "cancel_at_period_end": true,
  "billing_thresholds": {
    "amount_gte": null,
    "reset_billing_cycle_anchor": null
  },
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null,
  "managed_payments": {
    "enabled": true
  },
  "billing_schedules": [
    {
      "applies_to": null,
      "bill_until": {
        "computed_timestamp": 2082605468,
        "duration": {
          "interval": "month",
          "interval_count": null
        },
        "timestamp": null,
        "type": "duration"
      },
      "key": "key"
    }
  ]
}

Retrieve a Customer tax ID

GET/v1/customers/{customer}/tax_ids/{id}

Retrieves the tax_id object with the given identifier.

Path parameters

  • customerstringRequired
  • idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The tax_id object.

GET /v1/customers/{customer}/tax_ids/{id}
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/tax_ids/txi_1Pgc6sB7WZ01zgkWXkvC78jZ \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "country": "DE",
  "created": 1234567890,
  "customer": "cus_QXg1o8vcGmoR32",
  "id": "txi_1Pgc6sB7WZ01zgkWXkvC78jZ",
  "livemode": false,
  "object": "tax_id",
  "owner": {
    "customer": "cus_QXg1o8vcGmoR32",
    "type": "customer",
    "customer_account": null
  },
  "type": "eu_vat",
  "value": "DE123456789",
  "verification": {
    "status": "pending",
    "verified_address": null,
    "verified_name": null
  },
  "customer_account": null
}

Delete a Customer tax ID

DELETE/v1/customers/{customer}/tax_ids/{id}

Deletes an existing tax_id object.

Path parameters

  • customerstringRequired
  • idstringRequired

Returns

The deleted_tax_id object.

DELETE /v1/customers/{customer}/tax_ids/{id}
curl -X DELETE https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/tax_ids/txi_1Pgc6sB7WZ01zgkWXkvC78jZ \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "txi_1Pgc6sB7WZ01zgkWXkvC78jZ",
  "object": "tax_id"
}

Verify a bank account

POST/v1/customers/{customer}/bank_accounts/{id}/verify

Verify a specified bank account for a given customer.

Path parameters

  • customerstringRequired
  • idstringRequired

Body parameters

  • amountsarray of integers

    Two positive integers, in *cents*, equal to the values of the microdeposits sent to the bank account.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The bank_account object.

POST /v1/customers/{customer}/bank_accounts/{id}/verify
curl -X POST https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/bank_accounts/ba_1PgagAB7WZ01zgkWr3DySp2Q/verify \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "account_holder_name": "Jane Austen",
  "account_holder_type": "company",
  "account_type": null,
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "customer": null,
  "fingerprint": "AuoSJ18zsVWV9SPc",
  "id": "ba_1PgagAB7WZ01zgkWr3DySp2Q",
  "last4": "6789",
  "metadata": {},
  "object": "bank_account",
  "routing_number": "110000000",
  "status": "new"
}

Verify a bank account

POST/v1/customers/{customer}/sources/{id}/verify

Verify a specified bank account for a given customer.

Path parameters

  • customerstringRequired
  • idstringRequired

Body parameters

  • amountsarray of integers

    Two positive integers, in *cents*, equal to the values of the microdeposits sent to the bank account.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The bank_account object.

POST /v1/customers/{customer}/sources/{id}/verify
curl -X POST https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/sources/ba_1PgagAB7WZ01zgkWr3DySp2Q/verify \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "account_holder_name": "Jane Austen",
  "account_holder_type": "company",
  "account_type": null,
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "customer": null,
  "fingerprint": "AuoSJ18zsVWV9SPc",
  "id": "ba_1PgagAB7WZ01zgkWr3DySp2Q",
  "last4": "6789",
  "metadata": {},
  "object": "bank_account",
  "routing_number": "110000000",
  "status": "new"
}

GET /v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount

GET/v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount

Path parameters

  • customerstringRequired
  • subscription_exposed_idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The discount object.

GET /v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount
curl https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/subscriptions/subscription_exposed_id_123/discount \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "checkout_session": null,
  "customer": "cus_QXg1o8vcGmoR32",
  "end": 1234567890,
  "id": "di_1Pgc6rB7WZ01zgkW7Al8Fal9",
  "invoice": null,
  "invoice_item": null,
  "object": "discount",
  "promotion_code": null,
  "start": 1234567890,
  "subscription": null,
  "subscription_item": null,
  "source": {
    "coupon": null,
    "type": "coupon"
  },
  "customer_account": null
}

Delete a customer discount

DELETE/v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount

Removes the currently applied discount on a customer.

Path parameters

  • customerstringRequired
  • subscription_exposed_idstringRequired

Returns

The deleted_discount object.

DELETE /v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount
curl -X DELETE https://api.knoxapi.com/v1/customers/cus_QXg1o8vcGmoR32/subscriptions/subscription_exposed_id_123/discount \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "",
  "object": "discount",
  "start": 1234567890,
  "checkout_session": null,
  "customer": null,
  "invoice": null,
  "invoice_item": null,
  "promotion_code": null,
  "subscription": null,
  "subscription_item": null,
  "source": {
    "coupon": null,
    "type": "coupon"
  },
  "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.