Subscription Billing

Subscriptions are a quick and simple way to provide products to your customers that involve recurring payments. By using Subscriptions you can confidently charge customers at fixed intervals with no extra hassle other than the initial setup.

Subscriptions work with already existing KOMOJU API endpoints. You can retain your implementation of our Token API to quickly integrate recurring payments into your platform.

Note, Subscriptions may not support all payment methods.

Getting Started

Example (Quick Start)

The quickest way to begin a Subscription involves two api calls.

The first is to create a customer resource on KOMOJU. This customer can be used for any number of your Subscriptions. Creating a customer can help you keep track of the status of an individuals recurring payments.

POST /api/v1/customers

curl -X POST \
  -u sk_123456: \
  -d "" \
  -d "payment_details[family_name]=Yamada" \
  -d "payment_details[given_name]=Taro" \
  -d "payment_details[month]=1" \
  -d "payment_details[number]=4111111111111111" \
  -d "payment_details[type]=credit_card" \
  -d "payment_details[year]=2018"

NOTE: This request requires sending us your customer's credit card information. We recommend you instead use the Hosted Page or Tokens for collecting sensitive information.

Please save the customer's id from the response. We also recommend storing their email address so that you can contact them when payment fails.

Using the customer id we can make the actual Subscription API call.

POST /api/v1/subscriptions

curl -X POST \
  -u sk_123456: \
  -d "customer=3lz38k1d12sr5e4ggchnhxdgk" \
  -d "amount=2000" \
  -d "currency=JPY" \
  -d "period=monthly"

Example (Token / MultiPay)

If you are already using the Tokens API endpoint or KOMOJU Multipay you can easily start creating Subscriptions.

curl -X POST \
  -u sk_123456: \
  -d "" \
  -d "payment_details=tok_d7d3b7ea7a6910f1076bf025ad3276dac9360c9b3307cb92d77c93b62556077f3ifq39h3wnrlgkttrjm8c6g2e"
curl -X POST \
  -u sk_123456: \
  -d "customer=3lz38k1d12sr5e4ggchnhxdgk" \
  -d "amount=2000" \
  -d "currency=JPY" \
  -d "period=monthly"


Request Parameter Description Value
customer The customer who is being subscribed. A customer resource id either from the dashboard or the customer API.
amount The amount to be charged on every occurrence. Must be equal or greater than 0. Use a '.' as a decimal separator, and no thousands separator. Example: 1234.56
currency 3 letter ISO currency code of the transaction. "JPY"
period The interval at which payment will occur. A value of either "weekly", "monthly", or "yearly".
metadata A set of configurable key/value pairs. Optional
Response Parameter Description
status Current state of Subscription. See Life Cycle below for more information.
payment_details Summary of payment source, useful for debugging why a payment is failing (ie. expired credit card)
retry_count Number of times payment capture has failed for current Subscription interval.
retry_at If payment failed, it will be retried again in 1 day. This give you time to fix issues.
next_capture_at Time at which next interval starts and payment is due.
ended_at Time that Subscription was either suspended or deleted.
payments KOMOJU id of past payments associated with this Subscription.

Life Cycle

A Subscription can be in one of 5 states:

Status Description
pending Initialized and ready to capture first payment.
active Captured previous payment and waiting for next interval.
retrying Failed to capture payment for interval.
suspended Suspended due to too many payment failures.
deleted Deleted by merchant.

Here is a summary of how Subscriptions transition between states:

  1. Subscription is created in pending state.
  2. Immediately tries to capture payment for interval and set status to active.
  3. If fails in pending state, immediately suspend the Subscription.
  4. Make next payment attempt when next_capture_at arrives.
    • If payment is captured stay in active state.
    • If payment fails set status to retrying and attempt again in 24 hours.
    • If payment fails more than 3 times (with each attempt spanning 24 hours), set status to suspended and no longer process it.
    • If merchant deletes Subscription set status to deleted and no longer process it.

Handling Failed Payments

  1. Receive the webhooks that a Subscription payment has failed.
  2. Ensure customer payment details are up to date and not expired.
  3. Contact customer to update their information if payments continue to fail.

Updating a Subscription

  1. Find the id of Subscription you would like to update.
  2. Use the Subscription API to delete the Subscription before its next_capture_date.
  3. Use the Subscription API to create new Subscription with updated values.
Note: Subscriptions start right away.

Stopping a Subscription

  1. Find the id of Subscription you would like to stop.
  2. Delete the Subscription.
  3. You can still view past payments from the Subscription but it will no longer charge the customer.


You will need to setup a webhook to receive Subscription notifications from KOMOJU. When a Subscription is created or processed KOMOJU will send a webhooks to your application. Your application must process these webhook and record the status of the Subscriptions.