---
title: "Create new customer and subscription"
method: POST
path: "/{companyDomain}/subscriptions"
---

# Create new customer and subscription

`POST /{companyDomain}/subscriptions`

## Path parameters

- `companyDomain` string, required

## Request body

- object
  - `firstName` string, required — The customer's first name
  - `lastName` string, required — The customer's last name
  - `email` string, required — The customer's email address
  - `cycleId` integer, required — The unique identifier of the cycle in Billsby
  - `Units` integer, required — The number of units included in the subscription (min. 1)
  - `address` object, required — The customer's address
    - `addressLine1` string
    - `addressLine2` string
    - `state` string — For US addresses, this must be the ISO two letter state code
    - `city` string
    - `country` string — The ISO three letter country code
    - `postCode` string
  - `shippingAddress` object — The customer's shipping address (if different to their billing address)
    - `addressLine1` string
    - `addressLine2` string
    - `state` string — For US addresses, this must be the ISO two letter state code
    - `city` string
    - `country` string — The ISO three letter country code
    - `postCode` string
  - `additionalEmail` string — Any additional email address provided by the customer
  - `phoneNumberDialCountry` string — The country associated with their phone number
  - `phoneNumberDialCode` string — The country code associated with their phone number
  - `phoneNumber` string — The customer's phone number. If phoneNumber is provided, then phoneNumberDialCountry and phoneNumberDialCode are required.
  - `marketingConsent` boolean — Has the customer given marketing consent; true or false
  - `customFieldResponse` object[] — Response to any custom field questions you want to add to the subscription
    - `customFieldId` integer — The unique ID associated with the customer field in Billsby
    - `value` string — The response to the custom field
  - `addOns` object[] — The add-ons that you want to include in the subscription
    - `addOnId` integer, required — The unique identifier of the add-ons in the Billsby platform
    - `quantity` integer — The quantity of the add-on if unit based
  - `allowances` integer[] — The IDs of any allowances you want to include in the subscription. For multiple allowances you can add the IDs separated by a comma
  - `couponCodes` object[] — The codes of any coupons you want to apply to the subscription
    - `planId` integer, required — The unique identifier of the plan in the Billsby platform
    - `couponCode` string — The coupon code to be used for the plan
  - `cardDetails` object, required — The payment card details of the customer
    - `fullName` string — The full name of the customer
    - `paymentCardToken` string — This can be found in the create token API response
    - `expiryMonth` integer — Customers two digit expiry month - i.e. "12"
    - `expiryYear` integer — Customers card expiry year - i.e. "2020"
    - `cardType` string — "visa" "master" "american_express"
    - `last4Digits` string — The last 4 digits of the customers card

## Response `200`

200

- object
  - `customerUniqueId` string
  - `subscriptionUniqueId` string

---

[API](https://skmtc.net/billsby/apis/billsby-api.md) · [All operations](https://skmtc.net/billsby/apis/billsby-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/billsby/billsby-api/versions/adcb2fd4c52f/schema)