Subscriptions

Subscriptions renew a customer on a recurring price. CHING handles the first charge, the renewal cron, retries on failure, and document issuance. A subscription's `status` is one of `active`, `trialing`, `incomplete`, `incomplete_expired`, `past_due`, or `canceled` - treat anything other than `active` or `trialing` as unbilled.

Use cases: Build SaaS billing, offer yearly plans, or run memberships with free trials.

POST/v1/subscriptions

Create a subscription and charge the first period immediately (unless the price has a trial, in which case the first charge runs at trial end).

If the first charge fails in live mode, the subscription is still created but with status incomplete and latest_charge pointing at the failed charge. The response is 200 - inspect data.status before granting access. Incomplete subs are moved to incomplete_expired after 23 hours if the payment is never completed, and the renewal cron does not bill them.

Body Parameters

Name	Type		Description
`customer`	string	required	The customer id.
`payment_method`	string		Active payment method id to charge on each renewal. Required for paid prices; may be omitted only when the price has unit_amount === 0 (free plan).
`price`	string	required	A recurring price id. Determines amount and renewal cadence.
`metadata`	object		Set of key-value pairs you can attach to the object for your own use. Returned as-is on retrieval.

Request

curl -X POST "https://api.ching.co.il/ching/v1/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "example_customer",
  "payment_method": "example_payment_method",
  "price": "example_price",
  "metadata": {}
}'

Response

{
  "success": true,
  "data": {
    "id": "sub_hXUPYOnvxp-q",
    "object": "subscription",
    "customer": "cus_V8ltq1pK_MWH",
    "default_payment_method": "pm_WMc9X22NT1af",
    "status": "active",
    "currency": "ils",
    "items": [
      {
        "id": "si_E4TEG8TRMHp-",
        "price": "price_QA8qF3B3VIqE",
        "quantity": 1
      }
    ],
    "billing_cycle_anchor": "2026-04-19T09:16:40.000Z",
    "current_period_start": "2026-04-19T09:16:40.000Z",
    "current_period_end": "2026-05-19T09:16:40.000Z",
    "cancel_at_period_end": false,
    "latest_charge": "ch_9mTPfRSDmEOU",
    "metadata": {},
    "livemode": false,
    "created": "2026-04-19T09:16:40.000Z"
  }
}

GET/v1/subscriptions

List the 100 most recent subscriptions, newest first. Line items are omitted here - fetch the full subscription to see them.

Request

curl -X GET "https://api.ching.co.il/ching/v1/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": [
    {
      "id": "sub_hXUPYOnvxp-q",
      "object": "subscription",
      "customer": "cus_V8ltq1pK_MWH",
      "default_payment_method": "pm_WMc9X22NT1af",
      "status": "active",
      "currency": "ils",
      "items": [],
      "billing_cycle_anchor": "2026-04-19T09:16:40.000Z",
      "current_period_start": "2026-04-19T09:16:40.000Z",
      "current_period_end": "2026-05-19T09:16:40.000Z",
      "cancel_at_period_end": false,
      "latest_charge": "ch_9mTPfRSDmEOU",
      "metadata": {},
      "livemode": false,
      "created": "2026-04-19T09:16:40.000Z"
    }
  ]
}

GET/v1/subscriptions/:id

Retrieve a subscription by its id, including expanded items.

Path Parameters

Name	Type		Description
`id`	string	required	The subscription id.

Request

curl -X GET "https://api.ching.co.il/ching/v1/subscriptions/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "id": "sub_hXUPYOnvxp-q",
    "object": "subscription",
    "customer": "cus_V8ltq1pK_MWH",
    "default_payment_method": "pm_WMc9X22NT1af",
    "status": "active",
    "currency": "ils",
    "items": [
      {
        "id": "si_E4TEG8TRMHp-",
        "price": "price_QA8qF3B3VIqE",
        "quantity": 1
      }
    ],
    "billing_cycle_anchor": "2026-04-19T09:16:40.000Z",
    "current_period_start": "2026-04-19T09:16:40.000Z",
    "current_period_end": "2026-05-19T09:16:40.000Z",
    "cancel_at_period_end": false,
    "latest_charge": "ch_9mTPfRSDmEOU",
    "metadata": {},
    "livemode": false,
    "created": "2026-04-19T09:16:40.000Z"
  }
}

POST/v1/subscriptions/:id/cancel

Cancel a subscription immediately or at period end.

Path Parameters

Name	Type		Description
`id`	string	required	The subscription id.

Body Parameters

Name	Type		Description
`cancel_at_period_end`	boolean		When true, the subscription stays active until the end of the current period and will not renew. When false or omitted, it is canceled immediately.

Request

curl -X POST "https://api.ching.co.il/ching/v1/subscriptions/:id/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "cancel_at_period_end": true
}'

Response

{
  "success": true,
  "data": {
    "id": "sub_hXUPYOnvxp-q",
    "status": "canceled",
    "cancel_at_period_end": false
  }
}