Skip to content
Developer Guide
/
/
List all invoices

Chaching API (1.0)

Chaching is a modern subscription-billing platform designed to simplify product management, customer lifecycle workflows, and recurring payments. It combines a clean dashboard for business users with a powerful API built for developers who need full automation and control.

Download OpenAPI description
api.json
api.yaml
Overview
Languages
Servers
Mock server
https://chaching.redocly.app/_mock/developer-guide/api

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.

Operations

Products

Products describe the specific goods or services you offer to your customers. For example, you might offer a Standard and Premium version of your goods or service; each version would be a separate Product.

Operations

Transactions

Transactions represent the payments and charges made by your customers.

Operations

Invoices

Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription.

Operations

List all invoices

Request

Retrieves a paginated list of all invoices for the authenticated account. Supports pagination and filtering.

Query
searchstring

{"status":"open,draft,paid,void", "customer":"cus_fa66daabf0b474b167e1d46c"}

Default ""
pagenumber>= 1
Default 1
takenumber[ 1 .. 50 ]
Default 10
Headers
cc-api-keystringrequired

Chaching API Key

curl -i -X GET \
  'https://chaching.redocly.app/_mock/developer-guide/api/invoices?page=1&take=10' \
  -H 'cc-api-key: string'

Responses

Successfully retrieved paginated list of invoices

Bodyapplication/json
dataArray of arraysrequired
metaobject(PageMetaDto)required
meta.​pagenumberrequired
meta.​takenumberrequired
meta.​itemsTotalnumberrequired
meta.​pagesTotalnumberrequired
Response
application/json
{
  "data": [
    []
  ],
  "meta": {
    "page": 0,
    "take": 0,
    "itemsTotal": 0,
    "pagesTotal": 0
  }
}

Create an invoice

Request

Creates a new invoice for a customer. The invoice will include line items, pricing, taxes, and other billing information. The invoice will be in draft status until paid or committed.

Headers
cc-api-keystringrequired

Chaching API Key

Bodyapplication/jsonrequired
collection_methodstringrequired

The collection method for this invoice.

Enum"charge_automatically""send_invoice"
Example: "charge_automatically"
customerstringrequired

The ID of the customer for whom the invoice is to be created.

Example: "cus_383fda0065594749023e8c8d"
due_datenumber

The date on which payment for this invoice is due. Valid only for invoices where collection_method=send_invoice.

Example: 1672531199
default_payment_methodstring

The default payment method to be used for this invoice. Valid only for invoices where collection_method=charge_automatically.

Example: "pm_1SfME4DZYOQH9uHkDutknty1"
itemsArray of objects(ItemsPublicDto)required

Array of products to be included in the invoice.

items[].​pricestring/^[a-z]+_[a-zA-Z0-9]+$/required

The price ID in friendly ID format.

Example: "price_4N2gcTPKLGscC1OtN5ICQiIj"
items[].​taxArray of strings

Array of tax IDs in friendly ID format.

Example: ["txr_dUhN2gnTAuEyTjHHVBr1eAZ8"]
items[].​quantitynumber>= 1required

The quantity of the product.

Example: 3
curl -i -X POST \
  https://chaching.redocly.app/_mock/developer-guide/api/invoices \
  -H 'Content-Type: application/json' \
  -H 'cc-api-key: string' \
  -d '{
    "collection_method": "charge_automatically",
    "customer": "cus_383fda0065594749023e8c8d",
    "due_date": 1672531199,
    "default_payment_method": "pm_1SfME4DZYOQH9uHkDutknty1",
    "items": [
      {
        "price": "price_4N2gcTPKLGscC1OtN5ICQiIj",
        "tax": [
          "txr_dUhN2gnTAuEyTjHHVBr1eAZ8"
        ],
        "quantity": 3
      }
    ]
  }'

Responses

Invoice successfully created

Bodyapplication/json
idstring(string)required

Unique identifier for the object.

Example: "a80baa67-1341-4184-b712-b6f9b85b5a2b"
objectstringrequired

String representing the object’s type.

Default "invoice"
Value"invoice"
Example: "invoice"
account_countrystring or null

Country of the account associated with the invoice (only US is supported).

Value"US"
Example: "US"
account_namestring or null

Name of the account associated with the invoice.

Example: "Acme Corp"
amount_duenumber>= 0required

Final amount due at this time for this invoice (in cents for USD).

Example: 1500
amount_paidnumber or null>= 0

The amount, in cents, that was paid.

Example: 500
amount_remainingnumber or null>= 0

The difference between amount_due and amount_paid, in cents.

Example: 1000
attempt_countnumber or null>= 0

Number of payment attempts made for this invoice.

Example: 1
attemptedboolean or null

Whether payment of this invoice was attempted.

Example: true
billing_reasonstring or null

Describes why this invoice was created.

Enum"subscription""manual"
Example: "subscription"
collection_methodstring or null

Collection method of this invoice.

Enum"charge_automatically""send_invoice"
Example: "charge_automatically"
creatednumber>= 0required

Time at which the object was created. Measured in seconds since the Unix epoch

Example: 1680645568
currencystring= 3 characters^[A-Z]{3}$required

Three-letter ISO currency code, in uppercase

Example: "USD"
customerstring or null

ID of the customer associated with this invoice.

Example: "cus_383fda0065594749023e8c8d"
customer_addressobject

The customer’s address.

customer_emailstring(email)required

Email of the customer associated with the invoice.

Example: "john.doe@example.com"
customer_namestringrequired

Name of the customer associated with the invoice.

Example: "John Doe"
customer_phonestring or null

Phone number of the customer.

Example: "+1234567890"
linesArray of arraysrequired

The individual line items that make up the invoice.

numberstringrequired

A unique, identifying string that appears on emails sent to the customer for this invoice.

Example: "INV-1001"
paidbooleanrequired

Whether payment was successfully collected for this invoice.

Example: true
period_endnumber or null>= 0

End of the usage period during which invoice items were added to this invoice.

Example: 1680645568
period_startnumber or null>= 0

Start of the usage period during which invoice items were added to this invoice.

Example: 1680645568
statusstringrequired

The status of the invoice, one of draft, open, paid, or void.

Enum"draft""open""paid""void"
Example: "paid"
status_transitionsobject or null

The timestamps at which the invoice status was updated.

subscriptionstring or null

The ID of the subscription that this invoice was prepared for, if any.

Example: "sub_Wm45f5PGQvv67azFeH1z7PO3"
subtotalnumber or null>= 0

Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied

Example: 1500
subtotal_excluding_taxnumber or null>= 0

The integer amount in cents representing the subtotal of the invoice before any invoice level discount or tax is applied

Example: 1500
taxnumber or null>= 0

The amount of tax on this invoice.

Example: 150
totalnumber or null>= 0

Total after discounts and taxes.

Example: 1650
total_excluding_taxnumber or null>= 0

The integer amount in cents representing the total amount of the invoice including all discounts but excluding all tax.

Example: 1500
total_taxesobject or null

The aggregate amounts calculated per tax rate for all line items.

Response
application/json
{
  "id": "a80baa67-1341-4184-b712-b6f9b85b5a2b",
  "object": "invoice",
  "account_country": "US",
  "account_name": "Acme Corp",
  "amount_due": 1500,
  "amount_paid": 500,
  "amount_remaining": 1000,
  "attempt_count": 1,
  "attempted": true,
  "billing_reason": "subscription",
  "collection_method": "charge_automatically",
  "created": 1680645568,
  "currency": "USD",
  "customer": "cus_383fda0065594749023e8c8d",
  "customer_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "123 Market St",
    "line2": "Apt 4B",
    "postal_code": "94103",
    "state": "CA"
  },
  "customer_email": "john.doe@example.com",
  "customer_name": "John Doe",
  "customer_phone": "+1234567890",
  "lines": [],
  "number": "INV-1001",
  "paid": true,
  "period_end": 1680645568,
  "period_start": 1680645568,
  "status": "paid",
  "status_transitions": {
    "finalized_at": 1680645568,
    "paid_at": 1680645568,
    "voided_at": 1680645568
  },
  "subscription": "sub_Wm45f5PGQvv67azFeH1z7PO3",
  "subtotal": 1500,
  "subtotal_excluding_tax": 1500,
  "tax": 150,
  "total": 1650,
  "total_excluding_tax": 1500,
  "total_taxes": {
    "amount": 150,
    "tax_behavior": "exclusive",
    "tax_rate": "txr_1S2tlWDZYOQH9uHkltYEi1ap",
    "taxable_amount": 1500
  }
}

Retrieve an invoice

Request

Retrieves a specific invoice by its unique identifier, including all invoice details, line items, and payment information.

Path
idstringrequired

Unique identifier of the invoice

Example: 84c413b1-cda9-4637-a75d-352e36274bf2
Headers
cc-api-keystringrequired

Chaching API Key

curl -i -X GET \
  https://chaching.redocly.app/_mock/developer-guide/api/invoices/84c413b1-cda9-4637-a75d-352e36274bf2 \
  -H 'cc-api-key: string'

Responses

Successfully retrieved the invoice

Bodyapplication/json
idstring(string)required

Unique identifier for the object.

Example: "a80baa67-1341-4184-b712-b6f9b85b5a2b"
objectstringrequired

String representing the object’s type.

Default "invoice"
Value"invoice"
Example: "invoice"
account_countrystring or null

Country of the account associated with the invoice (only US is supported).

Value"US"
Example: "US"
account_namestring or null

Name of the account associated with the invoice.

Example: "Acme Corp"
amount_duenumber>= 0required

Final amount due at this time for this invoice (in cents for USD).

Example: 1500
amount_paidnumber or null>= 0

The amount, in cents, that was paid.

Example: 500
amount_remainingnumber or null>= 0

The difference between amount_due and amount_paid, in cents.

Example: 1000
attempt_countnumber or null>= 0

Number of payment attempts made for this invoice.

Example: 1
attemptedboolean or null

Whether payment of this invoice was attempted.

Example: true
billing_reasonstring or null

Describes why this invoice was created.

Enum"subscription""manual"
Example: "subscription"
collection_methodstring or null

Collection method of this invoice.

Enum"charge_automatically""send_invoice"
Example: "charge_automatically"
creatednumber>= 0required

Time at which the object was created. Measured in seconds since the Unix epoch

Example: 1680645568
currencystring= 3 characters^[A-Z]{3}$required

Three-letter ISO currency code, in uppercase

Example: "USD"
customerstring or null

ID of the customer associated with this invoice.

Example: "cus_383fda0065594749023e8c8d"
customer_addressobject

The customer’s address.

customer_emailstring(email)required

Email of the customer associated with the invoice.

Example: "john.doe@example.com"
customer_namestringrequired

Name of the customer associated with the invoice.

Example: "John Doe"
customer_phonestring or null

Phone number of the customer.

Example: "+1234567890"
linesArray of arraysrequired

The individual line items that make up the invoice.

numberstringrequired

A unique, identifying string that appears on emails sent to the customer for this invoice.

Example: "INV-1001"
paidbooleanrequired

Whether payment was successfully collected for this invoice.

Example: true
period_endnumber or null>= 0

End of the usage period during which invoice items were added to this invoice.

Example: 1680645568
period_startnumber or null>= 0

Start of the usage period during which invoice items were added to this invoice.

Example: 1680645568
statusstringrequired

The status of the invoice, one of draft, open, paid, or void.

Enum"draft""open""paid""void"
Example: "paid"
status_transitionsobject or null

The timestamps at which the invoice status was updated.

subscriptionstring or null

The ID of the subscription that this invoice was prepared for, if any.

Example: "sub_Wm45f5PGQvv67azFeH1z7PO3"
subtotalnumber or null>= 0

Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied

Example: 1500
subtotal_excluding_taxnumber or null>= 0

The integer amount in cents representing the subtotal of the invoice before any invoice level discount or tax is applied

Example: 1500
taxnumber or null>= 0

The amount of tax on this invoice.

Example: 150
totalnumber or null>= 0

Total after discounts and taxes.

Example: 1650
total_excluding_taxnumber or null>= 0

The integer amount in cents representing the total amount of the invoice including all discounts but excluding all tax.

Example: 1500
total_taxesobject or null

The aggregate amounts calculated per tax rate for all line items.

Response
application/json
{
  "id": "a80baa67-1341-4184-b712-b6f9b85b5a2b",
  "object": "invoice",
  "account_country": "US",
  "account_name": "Acme Corp",
  "amount_due": 1500,
  "amount_paid": 500,
  "amount_remaining": 1000,
  "attempt_count": 1,
  "attempted": true,
  "billing_reason": "subscription",
  "collection_method": "charge_automatically",
  "created": 1680645568,
  "currency": "USD",
  "customer": "cus_383fda0065594749023e8c8d",
  "customer_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "123 Market St",
    "line2": "Apt 4B",
    "postal_code": "94103",
    "state": "CA"
  },
  "customer_email": "john.doe@example.com",
  "customer_name": "John Doe",
  "customer_phone": "+1234567890",
  "lines": [],
  "number": "INV-1001",
  "paid": true,
  "period_end": 1680645568,
  "period_start": 1680645568,
  "status": "paid",
  "status_transitions": {
    "finalized_at": 1680645568,
    "paid_at": 1680645568,
    "voided_at": 1680645568
  },
  "subscription": "sub_Wm45f5PGQvv67azFeH1z7PO3",
  "subtotal": 1500,
  "subtotal_excluding_tax": 1500,
  "tax": 150,
  "total": 1650,
  "total_excluding_tax": 1500,
  "total_taxes": {
    "amount": 150,
    "tax_behavior": "exclusive",
    "tax_rate": "txr_1S2tlWDZYOQH9uHkltYEi1ap",
    "taxable_amount": 1500
  }
}

Pay an invoice

Request

Pays an invoice. This action will attempt to charge the customer using the payment method on file and finalize the invoice.

Path
idstringrequired

Unique identifier of the invoice to pay

Example: 84c413b1-cda9-4637-a75d-352e36274bf2
Headers
cc-api-keystringrequired

Chaching API Key

curl -i -X PUT \
  https://chaching.redocly.app/_mock/developer-guide/api/invoices/84c413b1-cda9-4637-a75d-352e36274bf2 \
  -H 'cc-api-key: string'

Responses

Invoice successfully paid

Void an invoice

Request

Voids a draft or open invoice. A voided invoice cannot be paid and is marked as cancelled. This action is irreversible.

Path
idstringrequired

Unique identifier of the invoice to void

Example: 84c413b1-cda9-4637-a75d-352e36274bf2
Headers
cc-api-keystringrequired

Chaching API Key

curl -i -X DELETE \
  https://chaching.redocly.app/_mock/developer-guide/api/invoices/84c413b1-cda9-4637-a75d-352e36274bf2 \
  -H 'cc-api-key: string'

Responses

Invoice successfully voided

List invoice transactions

Request

Retrieves a paginated list of all transactions associated with a specific invoice, including payment attempts, refunds, and adjustments.

Path
idstringrequired
Query
searchstring
Default ""
pagenumber>= 1
Default 1
takenumber[ 1 .. 50 ]
Default 10
Headers
cc-api-keystringrequired

Chaching API Key

curl -i -X GET \
  'https://chaching.redocly.app/_mock/developer-guide/api/invoices/{id}/transactions?page=1&take=10' \
  -H 'cc-api-key: string'

Responses

Successfully retrieved paginated list of invoice transactions

Bodyapplication/json
dataArray of arraysrequired
metaobject(PageMetaDto)required
meta.​pagenumberrequired
meta.​takenumberrequired
meta.​itemsTotalnumberrequired
meta.​pagesTotalnumberrequired
Response
application/json
{
  "data": [
    []
  ],
  "meta": {
    "page": 0,
    "take": 0,
    "itemsTotal": 0,
    "pagesTotal": 0
  }
}

Retrieve invoice transaction

Request

Retrieves detailed information about a specific transaction associated with an invoice.

Path
idstringrequired

Unique identifier of the invoice

Example: 84c413b1-cda9-4637-a75d-352e36274bf2
transactionIdstringrequired

Unique identifier of the transaction

Example: 1ac67144-c4eb-4977-a185-674278685a5f
Headers
cc-api-keystringrequired

Chaching API Key

curl -i -X GET \
  https://chaching.redocly.app/_mock/developer-guide/api/invoices/84c413b1-cda9-4637-a75d-352e36274bf2/transactions/1ac67144-c4eb-4977-a185-674278685a5f \
  -H 'cc-api-key: string'

Responses

Successfully retrieved transaction details

Bodyapplication/json
idstringrequired

Unique identifier for the object.

Example: "txn_1MiN3gLkdIwHu7ixxapQrznl"
objectstringrequired

String representing the object’s type.

Example: "balance_transaction"
amountnumberrequired

Gross amount of this transaction (in cents).

Example: -400
payment_methodstringrequired

ID of the payment method used in this transaction.

Example: "pm_1MiN3gLkdIwHu7ixxYzWqR2b"
balance_typestringrequired

The balance type of the transaction.

Example: "default"
available_onnumberrequired

The date that the transaction’s net funds become available in the Stripe balance.

Example: 1678043844
creatednumberrequired

The date the transaction was created.

Example: 1678043844
currencystringrequired

Three-letter ISO currency code.

Example: "usd"
descriptionstring

Description of the transaction.

Example: "Transfer to acct_1MiN3gLkdIwHu7ix"
exchange_ratenumber

The exchange rate applied to this transaction.

Example: null
feenumberrequired

The fee applied to this transaction (in cents).

Example: 0
fee_detailsArray of stringsrequired

Detailed breakdown of fees (in cents) paid for this transaction.

Example: []
netnumberrequired

The net amount of this transaction (in cents).

Example: -400
statusstringrequired

The status of the transaction.

Example: "available"
typestringrequired

The type of the transaction.

Example: "transfer"
Response
application/json
{
  "id": "txn_1MiN3gLkdIwHu7ixxapQrznl",
  "object": "balance_transaction",
  "amount": -400,
  "payment_method": "pm_1MiN3gLkdIwHu7ixxYzWqR2b",
  "balance_type": "default",
  "available_on": 1678043844,
  "created": 1678043844,
  "currency": "usd",
  "description": "Transfer to acct_1MiN3gLkdIwHu7ix",
  "exchange_rate": null,
  "fee": 0,
  "fee_details": [],
  "net": -400,
  "status": "available",
  "type": "transfer"
}

TaxRates

TaxRates allow you to calculate the tax to collect from your customer.

Operations

Prices

This object represents a price in your Chaching account. Use it to define the cost of your products, configure one-time or recurring billing intervals, specify tax behavior, and manage pricing updates or deactivations for your offerings.

Operations

Subscriptions

Subscriptions are a way to charge your customers on a recurring basis. They can be used for products or services that are delivered over time, such as memberships or software licenses.

Operations

Balance

Balances represent the amount of money in your account. You can use balances to track your income and expenses, and to make payments to your customers or vendors.

Operations

Payment Methods

Payment Methods represent a way to collect payment from your customers. They can be attached to customers to make charging easier and more efficient.

Operations