Subscription: Create

post

https://komoju.com/api/v1/subscriptions

Create a new subscription. A subscription represents a recurring payment. Recurring payments may be on a weekly, monthly, or yearly basis, specified by the period parameter.

In order to create a subscription, a customer ID must be supplied. The customer object contains saved payment info, which is regularly charged by the subscription.

Subscriptions support fixed billing dates via payment_cycle and proration via proration_logic (prorata or none). When prorata is specified, a prorated amount is charged immediately for the period between creation and the resolved first anchor date, and full recurring charges commence on that anchor date. If the anchor date resolves to one full period or more in the future, no prorated charge is taken and the subscription enters an awaiting status instead. When none is specified (or defaulted when payment_cycle is provided without proration_logic), no initial charge is taken, the subscription enters an awaiting status, and the first full charge occurs on the anchor date. If the anchor date is today or in the past, the full amount is captured immediately and recurring charges continue from that anchor.

A subscription can't be modified once it's created. To change a subscription, you must delete it and create a new one. Deleting a subscription sets its status to deleted.

Body Params

customer

string

required

length between 25 and 25

A unique 25-character alphanumeric resource identifier.

amount

int32

required

≥ 0

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

currency

string

enum

required

3-letter ISO currency code.

period

string

enum

required

Interval for subscription payments

Allowed:

metadata

object

Store any additional data you want to associate with the subscription.
The object's keys and values must be strings.
Keys have a maximum length of 30 characters.
Values have a maximum length of 2000 characters.

proration_logic

string

enum

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.

Allowed:

payment_cycle

object

Payment cycle configuration when creating a subscription with a fixed billing date.

Response

200200 response