Create subscription

Create a subscription (and optionally customer). Payment information can be obtained in one of the following ways:

  • A reference to an existing payment method for the customer can be given.
  • A reference to a customer payment method obtained with Billwerk+Optimize Checkout
  • Let the system send a signup receipt email to the customer with link to hosted payment information page for the subscription.
  • Handle the gathering of payment information self, e.g. by using the link to the hosted payment information page.

The parameter start_date is optional and indicates when the subscription is eligible to begin the first billing period. Whether the first billing period i starting at start_date depends on the schedule type on the plan for the subscription. If a fixed day schedule type is used, the first billing period will start on the first fixed day after start_date.

A subscription creation can be made conditional on a successful payment of the first invoice. See the parameter conditional_create. This will require a signup method of source, and the subscription must be eligible for billing for the first period right away.

When creating a subscription either a reference to an existing customer must be provided, or a customer can be created in the same operation using the parameter create_customer. The operation is atomic, so if subscription create fails, no customer will be created.

An example of how to use the create subscription API operation can be fore here.

To add subscription add-ons when creating a list of CreateSubscriptionAddOn</æ> objects can be provided in parameter add_ons. An example on the use of add-ons can be found here.

Additional costs can be added to a subscription at creation time by providing a list of CreateSubscriptionAdditionalCost objects in parameter additional_costs.


The operation can generate the following errors beside the generic HTTP error codes described here.

Error code HTTP codeDescription
9404Customer not found
10404Subscription plan provided not found
11400Duplicate handle - subscription handle, additional cost handle or subscription add-on handle already used
14400End date must be in the future
19404Customer card provided as source but cannot be found
34400Invalid card token provided as source
37 400Start date if provided cannot be more than one period in the past, e.g. one month.
75400Subscription not eligible for invoice. This error is returned if the conditional_create parameter is set to true, but the subscription does not have a plan resulting in an invoice right away. This is the case for subscription plans with fixed day billing. E.g. on the first of every month.
83404 Discount not found
85 400Multiple discounts not allowed
86404Coupon not found or not eligible
87400Coupon already used
103400Card token already used
104400Card token has expired
110400Unknown or missing source argument
111400Source not allowed for signup method
113404Add-on not found
114400Add-on already added or multiple occurences of same add-on in request without explicit unique subscription add-on handle
115 400 Add-on quantity not allowed for on-off add-on type
116400Add-on not eligible for subscription plan
169404Entitlement not found
Click Try It! to start a request and see the response here!