# Create a subscription

Creates a new subscription object. The subscription is billed to the customer's current default card.

Endpoint: POST /subscriptions
Version: 1.0.0
Security: BasicAuth

## Request fields (application/x-www-form-urlencoded):

  - `customerId` (string, required)
    Identifier of the customer who will be the owner of this subscription.
    Example: cust_AoR0wvgntQWRUYMdZNLYMz5R

  - `planId` (string, required)
    Identifier of the plan that will be assigned to this subscription.
    Example: plan_bLu3vzO8yhAFhbxFEadm6HUV

  - `card` (any)

  - `card.number` (string, required)
    The card number.
    Example: 4242424242424242

  - `card.expMonth` (string, required)
    Two-digit expiration month.
    Example: 12

  - `card.expYear` (string, required)
    Four-digit expiration year.
    Example: 2030

  - `card.cvc` (string, required)
    Card verification code.
    Example: 123

  - `card.cardholderName` (string)
    Name of the cardholder.
    Example: John Doe

  - `card.addressLine1` (string)
    Example: 1234 Market St

  - `card.addressLine2` (string)
    Example: Suite 500

  - `card.addressCity` (string)
    Example: San Francisco

  - `card.addressState` (string)
    Example: CA

  - `card.addressZip` (string)
    Example: 94103

  - `card.addressCountry` (string)
    Country represented as a three-letter ISO country code.
    Example: USA

  - `card.fraudCheckData` (object)
    Additional data used for fraud protection.

  - `card.fraudCheckData.ipAddress` (string)
    IP address of the user.
    Example: 203.0.113.42

  - `card.fraudCheckData.ipCountry` (string)
    Country derived from the user's IP address (two-letter ISO country code).
    Example: US

  - `card.fraudCheckData.email` (string)
    E-mail address of the user.
    Example: john.doe@example.com

  - `card.fraudCheckData.phone` (string)
    Phone number of the user.
    Example: +14155550132

  - `card.fraudCheckData.userAgent` (string)
    Value of the "User-Agent" HTTP header sent by the user.
    Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36

  - `card.fraudCheckData.acceptLanguage` (string)
    Value of the "Accept-Language" HTTP header sent by the user.
    Example: en-US,en;q=0.9

  - `card.fraudCheckData.browserFingerprint` (string)
    Hashed device identifier, available if Shift4.js was used to create the token.
    Example: 35a05229011ab99930545a2e1b2edc4e

  - `quantity` (integer)
    Multiplier applied to the amount defined in the plan. For example, a plan with amount=100 used in a subscription with quantity=5 will result in charges with amount=500.
    Example: 1

  - `captureCharges` (boolean)
    Whether charges created by this subscription are captured immediately (see the captured attribute in the charge request). If set to false, you need to manually capture each charge created by this subscription.

  - `trialEnd` (integer)
    Unix timestamp defining the end of the trial period for this subscription. If provided, it overrides the trial setting defined in the plan.
    Example: 1714521600

  - `shipping` (object)
    Shipping details for this subscription.

  - `shipping.name` (string)
    Example: John Doe

  - `shipping.phone` (string)
    Example: +14155550132

  - `shipping.address` (object)
    A postal address.

  - `shipping.address.line1` (string)
    Example: 1234 Market St

  - `shipping.address.line2` (string)
    Example: Suite 500

  - `shipping.address.zip` (string)
    Example: 94103

  - `shipping.address.city` (string)
    Example: San Francisco

  - `shipping.address.state` (string)
    Example: CA

  - `shipping.address.country` (string)
    Two-letter ISO 3166-1 country code
    Example: US

  - `billing` (object)
    Billing details for this subscription.

  - `billing.name` (string)
    Example: John Doe

  - `billing.email` (string)
    Example: john.doe@example.com

  - `billing.phone` (string)
    Example: +14155550132

  - `billing.vat` (string)
    Tax identification number
    Example: US123456789

  - `merchantAccountId` (string)
    Identifier of the merchant account that will be used to create charges for this subscription.
    Example: ma_RHCN1yhubdBpSCgKcYAGb0xH

## Response 200 fields (application/json):

  - `id` (string)
    Unique identifier for the subscription
    Example: sub_vrEaVmRDW0oKz8ycyy8Yc4l5

  - `created` (integer)
    Unix timestamp when the subscription was created
    Example: 1711929600

  - `objectType` (string)
    Object type identifier
    Enum: "subscription"

  - `planId` (string)
    Identifier of the plan assigned to this subscription.
    Example: plan_bLu3vzO8yhAFhbxFEadm6HUV

  - `customerId` (string)
    Identifier of the customer who is the owner of this subscription.
    Example: cust_AoR0wvgntQWRUYMdZNLYMz5R

  - `quantity` (integer)
    Multiplier applied to the amount defined in the plan. For example, a plan with amount=100 used in a subscription with quantity=5 will result in charges with amount=500.
    Example: 1

  - `captureCharges` (boolean)
    Whether charges created by this subscription are captured immediately (see the captured attribute in the charge request). If set to false, you need to manually capture each charge created by this subscription.
    Example: true

  - `status` (string)
    Status of this subscription:
- `trialing` - subscription was created from a plan with trial days and is still in the trial period.
- `active` - subscription is active and will be renewed after the end of the current billing cycle.
- `past_due` - renewing of the subscription has failed.
- `canceled` - subscription was manually canceled, or all retry renewal attempts have failed.
- `unpaid` - all retry renewal attempts have failed.
- `incomplete` - the first charge has failed on subscription creation.
Note that the resulting status when all renewal retry attempts have failed depends on your account settings.
    Enum: "trialing", "active", "past_due", "canceled", "unpaid", "incomplete"

  - `remainingBillingCycles` (integer)
    Defines how many billing cycles remain before this subscription is automatically canceled. Value of null means no limit on the number of charges.
    Example: 12

  - `start` (integer)
    Date the subscription started using the current plan. Will have a different value than created if the subscription plan was changed.
    Example: 1711929600

  - `currentPeriodStart` (integer)
    Start of the current billing period. For an active subscription this should match the time of the last rebill, but can be different if there was a problem creating the rebill charge (for example, because of a declined charge).
    Example: 1711929600

  - `currentPeriodEnd` (integer)
    End of the current billing period. For an active subscription this is the time when the next rebill will be attempted.
    Example: 1714521600

  - `canceledAt` (integer)
    The date when the subscription was requested to be canceled.
    Example: 1712534400

  - `endedAt` (integer)
    The date when the subscription was canceled. Will have a different value than canceledAt if the subscription was canceled with atPeriodEnd=true.
    Example: 1714521600

  - `trialStart` (integer)
    Start of the trial period.
    Example: 1711929600

  - `trialEnd` (integer)
    End of the trial period.
    Example: 1714521600

  - `cancelAtPeriodEnd` (boolean)
    If set to true, then the subscription will be canceled at the end of the current billing period.
    Example: false

  - `shipping` (object)
    Shipping details for this subscription.

  - `shipping.name` (string)
    Example: John Doe

  - `shipping.phone` (string)
    Example: +14155550132

  - `shipping.address` (object)
    A postal address.

  - `shipping.address.line1` (string)
    Example: 1234 Market St

  - `shipping.address.line2` (string)
    Example: Suite 500

  - `shipping.address.zip` (string)
    Example: 94103

  - `shipping.address.city` (string)
    Example: San Francisco

  - `shipping.address.state` (string)
    Example: CA

  - `shipping.address.country` (string)
    Two-letter ISO 3166-1 country code
    Example: US

  - `billing` (object)
    Billing details for this subscription.

  - `billing.name` (string)
    Example: John Doe

  - `billing.email` (string)
    Example: john.doe@example.com

  - `billing.phone` (string)
    Example: +14155550132

  - `billing.vat` (string)
    Tax identification number
    Example: US123456789

  - `merchantAccountId` (string)
    Identifier of the merchant account that will be used to create charges for this subscription.
    Example: ma_RHCN1yhubdBpSCgKcYAGb0xH

## Response 400 fields (application/json):

  - `error` (object)

  - `error.type` (string)
    Error type
    Enum: "invalid_request", "card_error", "gateway_error"

  - `error.code` (string)
    Machine-readable error code
    Example: invalid_number

  - `error.message` (string)
    Human-readable error message
    Example: Requested object does not exist

  - `error.chargeId` (string)
    ID of the charge associated with this error (if applicable)
    Example: char_ORVCrwOrTkGsDwM3H50OIW7Q

## Response 402 fields (application/json):

  - `error` (object)

  - `error.type` (string)
    Error type
    Enum: "invalid_request", "card_error", "gateway_error"

  - `error.code` (string)
    Machine-readable error code
    Example: invalid_number

  - `error.message` (string)
    Human-readable error message
    Example: Requested object does not exist

  - `error.chargeId` (string)
    ID of the charge associated with this error (if applicable)
    Example: char_ORVCrwOrTkGsDwM3H50OIW7Q