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.
Errors
The operation can generate the following errors beside the generic HTTP error codes described here.
| Error code | HTTP code | Description |
|---|---|---|
9 | 404 | Customer not found |
10 | 404 | Subscription plan provided not found |
11 | 400 | Duplicate handle - subscription handle, additional cost handle or subscription add-on handle already used |
14 | 400 | End date must be in the future |
19 | 404 | Customer card provided as source but cannot be found |
34 | 400 | Invalid card token provided as source |
37 | 400 | Start date if provided cannot be more than one period in the past, e.g. one month. |
75 | 400 | Subscription 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. |
83 | 404 | Discount not found |
85 | 400 | Multiple discounts not allowed |
86 | 404 | Coupon not found or not eligible |
87 | 400 | Coupon already used |
103 | 400 | Card token already used |
104 | 400 | Card token has expired |
110 | 400 | Unknown or missing source argument |
111 | 400 | Source not allowed for signup method |
113 | 404 | Add-on not found |
114 | 400 | Add-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 |
116 | 400 | Add-on not eligible for subscription plan |
169 | 404 | Entitlement not found |