Skip to main content

Create a subscription

POST 

/subscriptions/subscriptions

Create a subscription

Request

Query Parameters

    filter string

Body

    data BuildSubscriptionrequired
    external_ref ExternalRef (string)

    Possible values: <= 2048 characters

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    account_id UUID (string)required

    The unique identifier.

    address_id UUID (string)

    The unique identifier.

    offering_external_ref ExternalRef (string)

    Possible values: <= 2048 characters

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    offering_id UUID (string)

    The unique identifier.

    plan_id UUID (string)

    The unique identifier.

    currency CurrencyIdentifier (string)required

    Possible values: <= 1024 characters

    The three-letter ISO currency code in uppercase.

    payment_authority object
    oneOf
    type stringrequired

    Possible values: [elastic_path_payments_stripe]

    The name of the payment gateway facilitating the secure transmission of payment data.

    customer_id string

    Possible values: >= 3 characters and <= 1024 characters

    The unique identifier for a customer.

    card_id string

    Possible values: >= 3 characters and <= 1024 characters

    The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the card_id and customer_id attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See Card declines.

    manual_payments ManualPayments (boolean)required

    When configured to true, no payment gateway is used and a pending payment is created. See External Payments.

    name stringrequired

    Possible values: >= 3 characters and <= 1024 characters

    email emailrequired

    Possible values: >= 3 characters and <= 1024 characters

    pending boolean

    Whether a subscription is pending activation or not. See Creating a pending subscription.

    offering OfferingAttributes
    external_ref ExternalRef (string)

    Possible values: <= 2048 characters

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    name stringrequired

    Possible values: >= 3 characters and <= 1024 characters

    The name of the offering.

    description string

    Possible values: <= 1024 characters

    The offering description to display to customers.

    products ProductAttributes[]

    Possible values: >= 1

  • Array [
  • external_ref ExternalRef (string)

    Possible values: <= 2048 characters

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    name stringrequired

    Possible values: >= 3 characters and <= 1024 characters

    The name of the product.

    description string

    Possible values: <= 1024 characters

    The product or service description to display to customers.

    sku string

    Possible values: <= 1024 characters

    A stock keeping unit for the product, if appropriate.

    main_image uri

    Possible values: <= 1024 characters

    A URL from which an image or file for the product can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use Create a File to upload your file and return an HREF link in the response. An extensive range of media and file extensions are supported.

    price Price
    property name* object

    The base price.

    amount int64required

    The value as a whole number of the currency's smallest subdivision.

    includes_tax boolean

    Indicates whether the amount includes any taxes.

    price_units object

    The timeframe during which the product price is applicable. For example, for a streaming service, the price is $12.99 and the unit is months and the amount is 1. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many products that all have different prices. Rather than having to create separate plans for each product, you can specify the timeframe during which the product price is applicable and then create one plan that determines the billing frequency for those products.

    unit stringrequired

    Possible values: [day, month]

    A unit of time.

    amount integerrequired

    Possible values: >= 1

    The number of days or months the period covers.

  • ]
  • plans object[]

    Possible values: >= 1

    selected_plan ExternalRef (string)

    Possible values: <= 2048 characters

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    meta SubscriptionMeta
    timestamps Timestampsrequired
    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

    canceled_at string

    The date and time a subscription was cancelled.

    paused_at string

    The date and time a subscription was paused.

    resumed_at string

    The date and time a subscription was resumed.

    end_date string

    The date and time a subscription will end.

    go_live_after string

    The date and time a subscription will go live and become active.

    go_live string

    The date and time a subscription was released from the pending state and made active.

    status Status (string)required

    Possible values: [active, inactive]

    The status of a subscription, either active or inactive.

    state SubscriptionState
    id UUID (string)

    The unique identifier.

    type SubscriptionStateType (string)required

    Possible values: [subscription_state]

    This represents the type of resource object being returned. Always subscription_state.

    attributes SubscriptionStateAttributesrequired
    action SubscriptionStateAction (string)required

    Possible values: [cancel, pause, resume, pending]

    The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a product.

    A subscription can have the following states; canceled, paused, or resumed.

    See Managing the subscription lifecycle.

    meta StateMetarequired
    created_at stringrequired

    The date and time a resource was created.

    manual_payments ManualPayments (boolean)required

    When configured to true, no payment gateway is used and a pending payment is created. See External Payments.

    canceled booleanrequired

    Whether a subscription is canceled or not.

    paused booleanrequired

    Whether a subscription is paused or not.

    closed booleanrequired

    Whether a subscription is closed or not.

    suspended booleanrequired

    Whether a subscription is suspended or not.

    pending booleanrequired

    Whether a subscription is pending activation or not.

    invoice_after stringrequired

    The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point.

Responses

Success. The subscription is created.

Schema
    data Subscription
    id UUID (string)

    The unique identifier.

    type SubscriptionType (string)required

    Possible values: [subscription]

    attributes SubscriptionAttributesrequired
    external_ref ExternalRef (string)

    Possible values: <= 2048 characters

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    account_id UUID (string)required

    The unique identifier.

    address_id UUID (string)

    The unique identifier.

    offering Offeringrequired
    id UUID (string)

    The unique identifier.

    type SubscriptionOfferingType (string)required

    Possible values: [subscription_offering]

    attributes OfferingAttributesrequired
    external_ref ExternalRef (string)

    Possible values: <= 2048 characters

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    name stringrequired

    Possible values: >= 3 characters and <= 1024 characters

    The name of the offering.

    description string

    Possible values: <= 1024 characters

    The offering description to display to customers.

    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

    relationships Relationships

    Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.

    anyOf
    title
    meta OfferingMetarequired
    external_product_refs string[]required
    owner stringrequired

    The owner of a resource, either store or organization.

    timestamps Timestampsrequired
    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

    plan_id UUID (string)required

    The unique identifier.

    currency CurrencyIdentifier (string)required

    Possible values: <= 1024 characters

    The three-letter ISO currency code in uppercase.

    payment_authority object
    oneOf
    type stringrequired

    Possible values: [elastic_path_payments_stripe]

    The name of the payment gateway facilitating the secure transmission of payment data.

    customer_id string

    Possible values: >= 3 characters and <= 1024 characters

    The unique identifier for a customer.

    card_id string

    Possible values: >= 3 characters and <= 1024 characters

    The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the card_id and customer_id attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See Card declines.

    relationships Relationships

    Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.

    anyOf
    title
    meta SubscriptionMetarequired
    owner stringrequired

    The owner of a resource, either store or organization.

    timestamps Timestampsrequired
    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

    canceled_at string

    The date and time a subscription was cancelled.

    paused_at string

    The date and time a subscription was paused.

    resumed_at string

    The date and time a subscription was resumed.

    end_date string

    The date and time a subscription will end.

    go_live_after string

    The date and time a subscription will go live and become active.

    go_live string

    The date and time a subscription was released from the pending state and made active.

    status Status (string)required

    Possible values: [active, inactive]

    The status of a subscription, either active or inactive.

    state SubscriptionState
    id UUID (string)

    The unique identifier.

    type SubscriptionStateType (string)required

    Possible values: [subscription_state]

    This represents the type of resource object being returned. Always subscription_state.

    attributes SubscriptionStateAttributesrequired
    action SubscriptionStateAction (string)required

    Possible values: [cancel, pause, resume, pending]

    The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a product.

    A subscription can have the following states; canceled, paused, or resumed.

    See Managing the subscription lifecycle.

    meta StateMetarequired
    created_at stringrequired

    The date and time a resource was created.

    manual_payments ManualPayments (boolean)required

    When configured to true, no payment gateway is used and a pending payment is created. See External Payments.

    canceled booleanrequired

    Whether a subscription is canceled or not.

    paused booleanrequired

    Whether a subscription is paused or not.

    closed booleanrequired

    Whether a subscription is closed or not.

    suspended booleanrequired

    Whether a subscription is suspended or not.

    pending booleanrequired

    Whether a subscription is pending activation or not.

    invoice_after stringrequired

    The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point.

Loading...