---
title: "Subscriptions"
description: "A **Subscription** charges a customer on a recurring schedule using a stored credit card token."
url: "https://docs.komoju.com/en/api-reference#2024-07-15/tag/subscriptions"
source_url: "https://docs.komoju.com/en/api-reference/2024-07-15/resources/subscriptions.md"
language: en
api_version: "2024-07-15"
---

# Subscriptions

A **Subscription** charges a customer on a recurring schedule using a stored credit card token. Subscriptions belong to a Customer, run at a fixed period (e.g. monthly), and automatically generate a Payment on each billing cycle.

## The Subscription object

A **Subscription** charges a customer on a recurring schedule using a
stored payment method. Subscriptions belong to a `Customer`, run at a fixed
`period` (e.g. monthly on a chosen day), and automatically generate a
`Payment` each billing cycle.

### Attributes

- **`id`** *string (UUID)* *required*

  A unique 25-character alphanumeric resource identifier.

- **`resource`** *string enum* *required*

  Resource type name, always "subscription".

- **`status`** *string* *required*

  Current status of the subscription (`pending`, `active`, `retrying`, `suspended`, `deleted`, or `awaiting`). Deleting a subscription sets its status to `deleted`.

- **`amount`** *integer (Amount)* *required*

  Amount greater than or equal to 0, in the lowest denomination of the
  currency (e.g. cents for USD).

- **`currency`** *string (Currency)* *required*

  3-letter ISO currency code.

- **`customer`** *object* *required*

- **`period`** *string (SubscriptionPeriod)* *required*

  Interval for subscription payments

- **`day`** *integer* *required*

  Day of the period on which the subscription is charged: day of the week (0–6, Sunday to Saturday) for `weekly`, day of the month (1–31) for `monthly`, and day of the year (1–366) for `yearly`.

- **`payment_details`** *object* *required*

- **`retry_count`** *integer* *required*

  Number of times payment has been retried after failure.

- **`retry_at`** *string or null* *required*

  Timestamp of the next scheduled payment retry, or null.

- **`next_capture_at`** *string* *required*

  Timestamp of the next scheduled subscription charge.

- **`created_at`** *string* *required*

  Timestamp when the subscription was created.

- **`started_at`** *string or null* *required*

  Timestamp when the subscription was first successfully captured, or null if awaiting payment.

- **`ended_at`** *string or null* *required*

  Timestamp when the subscription ended, or null if still active.

- **`metadata`** *object* *required*

  Arbitrary key-value metadata attached to the subscription.

- **`payments`** *array of string (UUID)* *required*

  Array of payment UUIDs associated with this subscription.

- **`proration_logic`** *string (SubscriptionProrationLogic) or null* *required*

  Proration logic to apply when creating a subscription with a payment cycle.

  - `prorata`: Charges a prorated amount immediately for the period between subscription creation and the anchor date, then charges the full recurring amount on the anchor date and subsequent cycles. If the anchor date is a full period or more in the future, no immediate charge is taken and the subscription enters an `awaiting` status until the anchor date.
  - `none`: Takes no payment immediately and sets the subscription status to `awaiting`. The first charge for the full amount occurs on the anchor date.

- **`payment_cycle`** *SubscriptionPaymentCycle object or null* *required*

  Payment cycle details for a subscription.

### Example

```json
{
  "id": "string",
  "resource": "subscription",
  "status": "active",
  "amount": 0,
  "currency": "JPY",
  "customer": {
    "id": 0,
    "uuid": "string",
    "merchant_id": 0,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "email": "string",
    "currency": "JPY",
    "locale": "ja",
    "name": "string",
    "phone": "string",
    "archived_at": "2024-01-01T00:00:00Z"
  },
  "period": "weekly",
  "day": 0,
  "payment_details": {
    "type": "string",
    "month": "string",
    "year": "string",
    "email": "string"
  },
  "retry_count": 0,
  "retry_at": "2024-01-01T00:00:00Z",
  "next_capture_at": "2024-01-01T00:00:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "started_at": "2024-01-01T00:00:00Z",
  "ended_at": "2024-01-01T00:00:00Z",
  "metadata": {},
  "payments": [
    "string"
  ],
  "proration_logic": "prorata",
  "payment_cycle": {
    "anchor_date": "2025-03-09",
    "timezone": "Asia/Tokyo"
  }
}
```

## Endpoints

### Customer: Show

- [GET /customers/{id}](https://docs.komoju.com/en/api-reference/2024-07-15/show-customer.md)

### Customer: Update

- [PATCH /customers/{id}](https://docs.komoju.com/en/api-reference/2024-07-15/update-customer.md)

### Customer: Destroy

- [DELETE /customers/{id}](https://docs.komoju.com/en/api-reference/2024-07-15/delete-customer.md)

### Customer: List

- [GET /customers](https://docs.komoju.com/en/api-reference/2024-07-15/list-customers.md)

### Customer: Create

- [POST /customers](https://docs.komoju.com/en/api-reference/2024-07-15/create-customer.md)

### Subscription: Show

- [GET /subscriptions/{id}](https://docs.komoju.com/en/api-reference/2024-07-15/show-subscription.md)

### Subscription: Destroy

- [DELETE /subscriptions/{id}](https://docs.komoju.com/en/api-reference/2024-07-15/delete-subscription.md)

### Subscription: List

- [GET /subscriptions](https://docs.komoju.com/en/api-reference/2024-07-15/list-subscriptions.md)

### Subscription: Create

- [POST /subscriptions](https://docs.komoju.com/en/api-reference/2024-07-15/create-subscription.md)