Skip to content
Developer Guide
/
/
Retrieve a subscription

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

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

List all subscriptions

Request

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

Query
searchstring

{"status":"active|cancelled|paused|scheduled|expired|trial", "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/subscriptions?page=1&take=10' \
  -H 'cc-api-key: string'

Responses

Successfully retrieved paginated list of subscriptions

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

Request

Creates a new subscription for a customer. The subscription will include product items, pricing, and billing information.

Headers
cc-api-keystringrequired

Chaching API Key

Bodyapplication/jsonrequired
customerstringrequired

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

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

Array of products to be included in the subscription.

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
trial_daysnumber>= 0required

The number of trial days for the subscription.

Example: 14
start_datenumberrequired

The day when subscription starts. The start_date must be a valid Unix timestamp (positive number) in seconds

Example: 1672531199
end_datenumber

The day when subscription ends. The end_date must be a valid Unix timestamp (positive number) in seconds

Example: 1672531199
start_billing_datenumber

The day when subscription starts billing. The start_billing_date must be a valid Unix timestamp (positive number) in seconds

Example: 1672531199
curl -i -X POST \
  https://chaching.redocly.app/_mock/developer-guide/api/subscriptions \
  -H 'Content-Type: application/json' \
  -H 'cc-api-key: string' \
  -d '{
    "customer": "cus_e29d2542e2615c78af0d313d",
    "items": [
      {
        "price": "price_4N2gcTPKLGscC1OtN5ICQiIj",
        "tax": [
          "txr_dUhN2gnTAuEyTjHHVBr1eAZ8"
        ],
        "quantity": 3
      }
    ],
    "trial_days": 14,
    "start_date": 1672531199,
    "end_date": 1672531199,
    "start_billing_date": 1672531199
  }'

Responses

Subscription successfully created

Bodyapplication/json
idstring^[a-z]+_[a-zA-Z0-9]+$required

Unique identifier for the subscription.

Example: "sub_2FdhgypnsJQn9mZlY5qGaElL"
objectstringrequired

String representing the object's type.

Default "subscription"
Value"subscription"
Example: "subscription"
billing_cycle_anchornumber>= 0required

Determines the date of the first full invoice, and, for plans with month or year intervals, the day of the month for subsequent invoices.

Example: 1679609767
cancel_atnumber or nullrequired

A date in the future at which the subscription will automatically get canceled.

Example: null
cancel_at_period_endbooleanrequired

Whether this subscription will (if status=active) or did (if status=canceled) cancel at the end of the current billing period.

Example: false
canceled_atnumber or nullrequired

If the subscription has been canceled, the date of that cancellation.

Example: null
collection_methodstringrequired

Either charge_automatically, or send_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: 1679609767
currencystring= 3 characters^[A-Z]{3}$required

Three-letter ISO currency code, in uppercase.

Example: "USD"
customerstringrequired

ID of the customer who owns the subscription.

Example: "cus_739c07713fd4b68565a969cd"
ended_atnumber or nullrequired

If the subscription has ended, the date the subscription ended.

Example: null
itemsobjectrequired

List of subscription items, each with an attached plan.

items.​objectstringrequired

String representing the object's type.

Default "list"
Example: "list"
items.​dataArray of arraysrequired

Array of subscription items.

items.​total_countnumber>= 0required

The total number of subscription items.

Example: 1
latest_invoicestringrequired

The most recent invoice this subscription has generated.

Example: "58d0f1c9-ca00-4998-8e89-d74a290b4df6"
start_datenumber>= 0required

Date when the subscription was first created.

Example: 1679609767
statusstringrequired

The status of the subscription.

Enum"active""scheduled""canceled""expired""trialing"
Example: "active"
trial_endnumber or nullrequired

If the subscription has a trial, the end of that trial.

Example: null
trial_startnumber or nullrequired

If the subscription has a trial, the beginning of that trial.

Example: null
Response
application/json
{
  "id": "sub_2FdhgypnsJQn9mZlY5qGaElL",
  "object": "subscription",
  "billing_cycle_anchor": 1679609767,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "collection_method": "charge_automatically",
  "created": 1679609767,
  "currency": "USD",
  "customer": "cus_739c07713fd4b68565a969cd",
  "ended_at": null,
  "items": {
    "object": "list",
    "data": [ … ],
    "total_count": 1
  },
  "latest_invoice": "58d0f1c9-ca00-4998-8e89-d74a290b4df6",
  "start_date": 1679609767,
  "status": "active",
  "trial_end": null,
  "trial_start": null
}

Retrieve a subscription

Request

Retrieves a specific subscription by its unique identifier.

Path
idstring^[a-z]+_[a-zA-Z0-9]+$required

Unique identifier of the subscription

Example: sub_2FdhgypnsJQn9mZlY5qGaElL
Headers
cc-api-keystringrequired

Chaching API Key

curl -i -X GET \
  https://chaching.redocly.app/_mock/developer-guide/api/subscriptions/sub_2FdhgypnsJQn9mZlY5qGaElL \
  -H 'cc-api-key: string'

Responses

Successfully retrieved the subscription

Bodyapplication/json
idstring^[a-z]+_[a-zA-Z0-9]+$required

Unique identifier for the subscription.

Example: "sub_2FdhgypnsJQn9mZlY5qGaElL"
objectstringrequired

String representing the object's type.

Default "subscription"
Value"subscription"
Example: "subscription"
billing_cycle_anchornumber>= 0required

Determines the date of the first full invoice, and, for plans with month or year intervals, the day of the month for subsequent invoices.

Example: 1679609767
cancel_atnumber or nullrequired

A date in the future at which the subscription will automatically get canceled.

Example: null
cancel_at_period_endbooleanrequired

Whether this subscription will (if status=active) or did (if status=canceled) cancel at the end of the current billing period.

Example: false
canceled_atnumber or nullrequired

If the subscription has been canceled, the date of that cancellation.

Example: null
collection_methodstringrequired

Either charge_automatically, or send_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: 1679609767
currencystring= 3 characters^[A-Z]{3}$required

Three-letter ISO currency code, in uppercase.

Example: "USD"
customerstringrequired

ID of the customer who owns the subscription.

Example: "cus_739c07713fd4b68565a969cd"
ended_atnumber or nullrequired

If the subscription has ended, the date the subscription ended.

Example: null
itemsobjectrequired

List of subscription items, each with an attached plan.

items.​objectstringrequired

String representing the object's type.

Default "list"
Example: "list"
items.​dataArray of arraysrequired

Array of subscription items.

items.​total_countnumber>= 0required

The total number of subscription items.

Example: 1
latest_invoicestringrequired

The most recent invoice this subscription has generated.

Example: "58d0f1c9-ca00-4998-8e89-d74a290b4df6"
start_datenumber>= 0required

Date when the subscription was first created.

Example: 1679609767
statusstringrequired

The status of the subscription.

Enum"active""scheduled""canceled""expired""trialing"
Example: "active"
trial_endnumber or nullrequired

If the subscription has a trial, the end of that trial.

Example: null
trial_startnumber or nullrequired

If the subscription has a trial, the beginning of that trial.

Example: null
Response
application/json
{
  "id": "sub_2FdhgypnsJQn9mZlY5qGaElL",
  "object": "subscription",
  "billing_cycle_anchor": 1679609767,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "collection_method": "charge_automatically",
  "created": 1679609767,
  "currency": "USD",
  "customer": "cus_739c07713fd4b68565a969cd",
  "ended_at": null,
  "items": {
    "object": "list",
    "data": [ … ],
    "total_count": 1
  },
  "latest_invoice": "58d0f1c9-ca00-4998-8e89-d74a290b4df6",
  "start_date": 1679609767,
  "status": "active",
  "trial_end": null,
  "trial_start": null
}

Update a subscription

Request

Updates an existing subscription by its unique identifier. Can modify items, pricing, billing information, and other subscription details.

Path
idstring^[a-z]+_[a-zA-Z0-9]+$required

Unique identifier of the subscription to update

Example: sub_2FdhgypnsJQn9mZlY5qGaElL
Headers
cc-api-keystringrequired

Chaching API Key

Bodyapplication/jsonrequired
customerstringrequired

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

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

Array of products to be included in the subscription.

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
trial_daysnumber>= 0required

The number of trial days for the subscription.

Example: 14
end_datenumber

The day when subscription ends. The end_date must be a valid Unix timestamp (positive number) in seconds

Example: 1672531199
curl -i -X PATCH \
  https://chaching.redocly.app/_mock/developer-guide/api/subscriptions/sub_2FdhgypnsJQn9mZlY5qGaElL \
  -H 'Content-Type: application/json' \
  -H 'cc-api-key: string' \
  -d '{
    "customer": "cus_e29d2542e2615c78af0d313d",
    "items": [
      {
        "price": "price_4N2gcTPKLGscC1OtN5ICQiIj",
        "tax": [
          "txr_dUhN2gnTAuEyTjHHVBr1eAZ8"
        ],
        "quantity": 3
      }
    ],
    "trial_days": 14,
    "end_date": 1672531199
  }'

Responses

Subscription successfully updated

Bodyapplication/json
idstring^[a-z]+_[a-zA-Z0-9]+$required

Unique identifier for the subscription.

Example: "sub_2FdhgypnsJQn9mZlY5qGaElL"
objectstringrequired

String representing the object's type.

Default "subscription"
Value"subscription"
Example: "subscription"
billing_cycle_anchornumber>= 0required

Determines the date of the first full invoice, and, for plans with month or year intervals, the day of the month for subsequent invoices.

Example: 1679609767
cancel_atnumber or nullrequired

A date in the future at which the subscription will automatically get canceled.

Example: null
cancel_at_period_endbooleanrequired

Whether this subscription will (if status=active) or did (if status=canceled) cancel at the end of the current billing period.

Example: false
canceled_atnumber or nullrequired

If the subscription has been canceled, the date of that cancellation.

Example: null
collection_methodstringrequired

Either charge_automatically, or send_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: 1679609767
currencystring= 3 characters^[A-Z]{3}$required

Three-letter ISO currency code, in uppercase.

Example: "USD"
customerstringrequired

ID of the customer who owns the subscription.

Example: "cus_739c07713fd4b68565a969cd"
ended_atnumber or nullrequired

If the subscription has ended, the date the subscription ended.

Example: null
itemsobjectrequired

List of subscription items, each with an attached plan.

items.​objectstringrequired

String representing the object's type.

Default "list"
Example: "list"
items.​dataArray of arraysrequired

Array of subscription items.

items.​total_countnumber>= 0required

The total number of subscription items.

Example: 1
latest_invoicestringrequired

The most recent invoice this subscription has generated.

Example: "58d0f1c9-ca00-4998-8e89-d74a290b4df6"
start_datenumber>= 0required

Date when the subscription was first created.

Example: 1679609767
statusstringrequired

The status of the subscription.

Enum"active""scheduled""canceled""expired""trialing"
Example: "active"
trial_endnumber or nullrequired

If the subscription has a trial, the end of that trial.

Example: null
trial_startnumber or nullrequired

If the subscription has a trial, the beginning of that trial.

Example: null
Response
application/json
{
  "id": "sub_2FdhgypnsJQn9mZlY5qGaElL",
  "object": "subscription",
  "billing_cycle_anchor": 1679609767,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "collection_method": "charge_automatically",
  "created": 1679609767,
  "currency": "USD",
  "customer": "cus_739c07713fd4b68565a969cd",
  "ended_at": null,
  "items": {
    "object": "list",
    "data": [ … ],
    "total_count": 1
  },
  "latest_invoice": "58d0f1c9-ca00-4998-8e89-d74a290b4df6",
  "start_date": 1679609767,
  "status": "active",
  "trial_end": null,
  "trial_start": null
}

Cancel a subscription

Request

Cancels an active subscription. The subscription will be terminated immediately or at the end of the current billing period based on configuration.

Path
idstring^[a-z]+_[a-zA-Z0-9]+$required

Unique identifier of the subscription to cancel

Example: sub_2FdhgypnsJQn9mZlY5qGaElL
Headers
cc-api-keystringrequired

Chaching API Key

curl -i -X DELETE \
  https://chaching.redocly.app/_mock/developer-guide/api/subscriptions/sub_2FdhgypnsJQn9mZlY5qGaElL \
  -H 'cc-api-key: string'

Responses

Subscription successfully cancelled

Pause a subscription

Request

Pauses an active subscription. No charges will be made while the subscription is paused. The subscription can be resumed later.

Path
idstring^[a-z]+_[a-zA-Z0-9]+$required

Unique identifier of the subscription to pause

Example: sub_2FdhgypnsJQn9mZlY5qGaElL
Headers
cc-api-keystringrequired

Chaching API Key

curl -i -X POST \
  https://chaching.redocly.app/_mock/developer-guide/api/subscriptions/sub_2FdhgypnsJQn9mZlY5qGaElL/pause \
  -H 'cc-api-key: string'

Responses

Subscription successfully paused

Response
No content

Resume a subscription

Request

Resumes a paused subscription. Billing will continue from where it was paused, and the subscription will be active again.

Path
idstring^[a-z]+_[a-zA-Z0-9]+$required

Unique identifier of the subscription to resume

Example: sub_2FdhgypnsJQn9mZlY5qGaElL
Headers
cc-api-keystringrequired

Chaching API Key

curl -i -X POST \
  https://chaching.redocly.app/_mock/developer-guide/api/subscriptions/sub_2FdhgypnsJQn9mZlY5qGaElL/resume \
  -H 'cc-api-key: string'

Responses

Subscription successfully resumed

Response
No content

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