Create Subscription

Create a subscription

POST/v2/subscriptions/subscriptions

Use it in a workflow

Add a step and choose the Elastic Path connector.
Pick the Create Subscription action (under Subscriptions).
Fill in the fields below, then reference the result from later steps as {{createSubscription.response.data}}.

Request

Query parameters

filterstring (string)

Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.

Request body

Enter the body as JSON in the step's Body field.

dataobjectrequired

external_refstring

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

account_idstring (uuid)required

The unique identifier.

address_idstring (uuid)

The unique identifier.

offering_external_refstring

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

offering_idstring (uuid)

The unique identifier.

plan_idstring (uuid)

The unique identifier.

pricing_option_idstring (uuid)

The unique identifier.

currencystringrequired

The three-letter [**ISO currency code**](https://www.iso.org/iso-4217-currency-codes.html) in uppercase.

payment_authorityobject1 fields

manual_paymentsbooleanrequired

When configured to true, no payment gateway is used and a pending payment is created. See [External Payments](/docs/api/subscriptions/invoices#external-payments).

Default false

namestringrequired

emailstring (email)required

pendingboolean

Whether a subscription is pending activation or not. See [Creating a pending subscription](/docs/api/subscriptions/subscriptions#creating-a-pending-subscription).

first_invoice_paidboolean

Indicates that payment for the first billing period of the subscription has already been taken. As well as creating the subscription a settled invoice is created to cover the first period.

started_atstring

When importing an active subscription from an existing system you can specify the date and time of the start of the most recent period. This may only be supplied when `first_invoice_paid` is true. As well as creating the subscription a settled invoice is created to cover the correct billing period.

override_first_period_end_datestring (date-time)

Optional. May only be set when `started_at` is set. When supplied, overrides the default first billing period end (start + 1 interval). The first billing period runs from the subscription start date to this date. The subscriber is charged the standard period price for the first period. Subsequent billing periods start from this date. Must be after the subscription start date.

offeringobject3 fields

featuresarray<oneOf>

Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering

plansarray<any>

pricing_optionsarray<any>

configured_featuresobject

Map of feature configurations keyed by plan UUID or external_ref

pricing_option_associationsobject

A map of plans keyed by plan UUID or external_ref to a list of associated pricing options, similarly keyed.

selected_planstring

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

selected_pricing_optionstring

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

orderobject2 fields

A subscription may optionally be associated with an item in an order by supplying both the order ID and the ID of the item within that order.

metaobject14 fields

json

{
  "data": {
    "account_id": "11111111-2222-3333-4444-555555555555",
    "currency": "USD",
    "manual_payments": false,
    "name": "Albert Einstein",
    "email": "albert@elasticpath.com",
    "external_ref": "abc123",
    "address_id": "11111111-2222-3333-4444-555555555555",
    "offering_external_ref": "abc123",
    "offering_id": "11111111-2222-3333-4444-555555555555",
    "plan_id": "11111111-2222-3333-4444-555555555555",
    "pricing_option_id": "11111111-2222-3333-4444-555555555555",
    "payment_authority": {
      "type": "elastic_path_payments_stripe"
    }
  }
}

Response

Returns 201 with an object. Read it in later steps with {{createSubscription.response.data.<field>}}.

dataobject

idstring (uuid)

The unique identifier.

typestringrequired

One ofsubscription

attributesobjectrequired8 fields

relationshipsany

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

metaobjectrequired14 fields

json

{
  "data": {
    "type": "subscription",
    "attributes": {
      "account_id": "11111111-2222-3333-4444-555555555555",
      "offering": {
        "type": "subscription_offering",
        "attributes": null,
        "meta": {
          "external_plan_refs": [
            "97dddc65-eabd-45d8-b45b-2ece5cfc8c50"
          ],
          "owner": "store",
          "timestamps": {
            "updated_at": "2017-01-10T11:41:19.244842Z",
            "created_at": "2017-01-10T11:41:19.244842Z"
          }
        },
        "id": "11111111-2222-3333-4444-555555555555",
        "relationships": {
          "pricing-options": {
            "links": {
              "related": "/offerings/:offering-id/pricing-options",
              "self": "/offerings/:offering-id"
            },
            "data": {
              "type": "offering-pricing-option",
              "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
            }
          }
        }
      },
      "pricing_option_id": "11111111-2222-3333-4444-555555555555",
      "plan_id": "11111111-2222-3333-4444-555555555555",
      "currency": "USD",
      "external_ref": "abc123",
      "address_id": "11111111-2222-3333-4444-555555555555",
      "payment_authority": {
        "type": "elastic_path_payments_stripe"
      }
    },
    "meta": {
      "owner": "store",
      "timestamps": null,
      "status": "active",
      "manual_payments": false,
      "first_invoice_prepaid": false,
      "canceled": true,
      "paused": true,
      "closed": true,
      "suspended": false,
      "pending": false,
      "invoice_after": "2017-01-10T11:41:19.244842Z",
      "state": {
        "type": "subscription_state",
        "attributes": {
          "action": "cancel",
          "cancel_immediately": false
        },
        "meta": {
          "created_at": "2017-01-10T11:41:19.244842Z"
        },
        "id": "11111111-2222-3333-4444-555555555555"
      }
    },
    "id": "11111111-2222-3333-4444-555555555555",
    "relationships": {
      "pricing-options": {
        "links": {
          "related": "/offerings/:offering-id/pricing-options",
          "self": "/offerings/:offering-id"
        },
        "data": {
          "type": "offering-pricing-option",
          "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
        }
      }
    }
  }
}

Need more? See the Elastic Path guide for connection setup and behaviour shared by every action.

Was this page helpful?