> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Subscription

> Creates a subscription for a saved customer against a saved payment method, with no new checkout — the one-click post-purchase upsell path, given a saved `provider_customer_id` and one or more `provider_price_id`s. Recurring and one-time prices are sent together in `items`; there is no separate `one_time_items` array.

The payment method is the supplied `provider_payment_method_id` when present, otherwise the customer's default payment method.

By default the first charge is taken during the request, **off-session**: a declined or authentication-required card returns an error and leaves no `incomplete` subscription behind, and a customer with no `provider_payment_method_id` and no default is blocked with a `400`.

Set `on_session: true` to defer that charge to a browser confirmation the customer completes while present. Nothing is charged during the request, so a first-time customer with no saved card can subscribe, and a decline instead surfaces client-side after a `200`, leaving the subscription `incomplete`. See `on_session` and `payment_confirmation` below.

Coupons and promotion codes can be applied at creation, on the whole subscription (`discounts`) or on a single line (`items[].discounts`) — this is the only place a discount reaches the **first** invoice. **A discount that covers the whole first charge leaves no payment method on file:** there is no payment to take, so nothing captures a card, and the first renewal after the coupon lapses has nothing to charge. If a discount may zero the first invoice, collect and pass `provider_payment_method_id` yourself.

Returns the created subscription in the same shape as `GET /subscriptions/{provider_subscription_id}`, plus the optional `payment_confirmation` block.



## OpenAPI

````yaml /openapi.json post /subscriptions
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /subscriptions:
    post:
      tags:
        - Subscriptions
      summary: Create Subscription
      description: >-
        Creates a subscription for a saved customer against a saved payment
        method, with no new checkout — the one-click post-purchase upsell path,
        given a saved `provider_customer_id` and one or more
        `provider_price_id`s. Recurring and one-time prices are sent together in
        `items`; there is no separate `one_time_items` array.


        The payment method is the supplied `provider_payment_method_id` when
        present, otherwise the customer's default payment method.


        By default the first charge is taken during the request,
        **off-session**: a declined or authentication-required card returns an
        error and leaves no `incomplete` subscription behind, and a customer
        with no `provider_payment_method_id` and no default is blocked with a
        `400`.


        Set `on_session: true` to defer that charge to a browser confirmation
        the customer completes while present. Nothing is charged during the
        request, so a first-time customer with no saved card can subscribe, and
        a decline instead surfaces client-side after a `200`, leaving the
        subscription `incomplete`. See `on_session` and `payment_confirmation`
        below.


        Coupons and promotion codes can be applied at creation, on the whole
        subscription (`discounts`) or on a single line (`items[].discounts`) —
        this is the only place a discount reaches the **first** invoice. **A
        discount that covers the whole first charge leaves no payment method on
        file:** there is no payment to take, so nothing captures a card, and the
        first renewal after the coupon lapses has nothing to charge. If a
        discount may zero the first invoice, collect and pass
        `provider_payment_method_id` yourself.


        Returns the created subscription in the same shape as `GET
        /subscriptions/{provider_subscription_id}`, plus the optional
        `payment_confirmation` block.
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
          description: >-
            Deduplicates retried requests with the same key and parameters
            instead of creating a second resource. Recommended: a
            **deterministic, order-scoped** value such as
            `initial-subscription:{provider_customer_id}:{order_id}` — a client
            that generates a fresh random value on retry defeats the
            deduplication and creates a second subscription. **Mint a new key
            for a genuinely new attempt.** Reusing a key replays the original
            response, so a retry after a `400` decline returns that same `400`
            instead of charging a replacement card, and changing `items` under
            an unchanged key is rejected as an idempotency conflict rather than
            retried. The replay window (roughly 24 hours) also outlives the
            subscription's own `incomplete_expired` deadline (roughly 20 hours),
            so once a prior attempt under a key has reached a terminal state, a
            genuinely new purchase needs a new key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider_customer_id:
                  type: string
                  description: Saved provider customer id (e.g. `test_customer_id`).
                provider_payment_method_id:
                  type: string
                  description: >-
                    Saved provider payment-method id (e.g.
                    `test_payment_method_id`). When provided, set as the new
                    subscription's default payment method. Charged off-session
                    during the request by default, or used as the method the
                    customer confirms when `on_session: true`. When omitted, the
                    customer's default payment method is used. On the
                    **off-session** posture a customer with no default is
                    rejected with a `400`; on the **on-session** posture the
                    field may be omitted for a customer with no saved method at
                    all — the browser confirmation collects it, which is what
                    makes a first purchase possible.
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      provider_price_id:
                        type: string
                        description: >-
                          Provider price id for a recurring or a one-time price
                          (e.g. `test_price_id`). Resolved with the provider
                          before the subscription is created, so an id the
                          provider does not have is a `404` naming it — no
                          subscription and no charge.
                      quantity:
                        type: number
                        description: Positive integer.
                      discounts:
                        type: array
                        items:
                          type: object
                          properties:
                            coupon:
                              type: string
                              description: >-
                                Provider coupon id. Exactly one of `coupon`,
                                `promotion_code` or `discount` per entry.
                            promotion_code:
                              type: string
                              description: >-
                                Provider promotion-code id. Exactly one of
                                `coupon`, `promotion_code` or `discount` per
                                entry.
                            discount:
                              type: string
                              description: >-
                                Provider id of an **existing** discount
                                (`di_...`) on this subscription or its billing
                                customer, to reuse it rather than create a new
                                one. Exactly one of `coupon`, `promotion_code`
                                or `discount` per entry.
                        description: >-
                          Discounts applied to **this item only**, same entry
                          shape as the top-level `discounts` — exactly one of
                          `coupon`, `promotion_code` or `discount` per entry.
                          Where the discount lands follows where the item lands:
                          a **recurring** price's discounts attach to the
                          subscription item, a **one-time** price's attach to
                          the invoice line it becomes on the first invoice.
                          Item-level discounts are applied before
                          subscription-level ones. An empty array is treated as
                          absent.
                    required:
                      - provider_price_id
                  description: >-
                    Non-empty. Carries **both** recurring and one-time prices —
                    send every price in this one array. You do not say which is
                    which: each `provider_price_id` is resolved with the
                    provider, and a recurring price becomes a subscription item
                    while a one-time price is billed once on the subscription's
                    first invoice. Must include exactly one recurring price,
                    with any number of one-time prices beside it: an `items`
                    array of only one-time prices, or with two or more recurring
                    prices, is rejected with a `400`. Pause, resume and cancel
                    act on the whole subscription, so create one subscription
                    per recurring product. A one-time price is charged
                    immediately **even when `trial_period_days` is set**: the
                    trial defers the recurring charge, not the one-time item,
                    which is what makes a "$1 first month then rebill" bundle a
                    single call. Each entry has a required `provider_price_id`
                    and optional `quantity`. A separate `one_time_items` array
                    is not accepted — a request that still sends it is rejected
                    with a `400` naming the field, so an upfront charge can
                    never be silently skipped; move those entries into `items`.
                    Invoice lines do not carry a coverage period.
                discounts:
                  type: array
                  items:
                    type: object
                    properties:
                      coupon:
                        type: string
                        description: >-
                          Provider coupon id. Exactly one of `coupon`,
                          `promotion_code` or `discount` per entry.
                      promotion_code:
                        type: string
                        description: >-
                          Provider promotion-code id. Exactly one of `coupon`,
                          `promotion_code` or `discount` per entry.
                      discount:
                        type: string
                        description: >-
                          Provider id of an **existing** discount (`di_...`) on
                          this subscription or its billing customer, to reuse it
                          rather than create a new one. Exactly one of `coupon`,
                          `promotion_code` or `discount` per entry.
                  description: >-
                    Discounts applied at creation, so the discount reaches the
                    **first** invoice — how long it keeps applying afterwards is
                    the coupon's own `duration`, not this field's. Each entry
                    must specify **exactly one** of `coupon`, `promotion_code`
                    or `discount`; sending two of them as non-empty strings, or
                    none of them, is a `400`. A blank or non-string member is
                    ignored rather than rejected, so `{"coupon": "",
                    "promotion_code": "test_promotion_code_id"}` is accepted as
                    a promotion-code discount. Ids are trimmed before use. An
                    **empty array is treated as absent** — identical to omitting
                    the field: the provider default applies, which inherits any
                    discount already on the billing customer. Per-item discounts
                    go on `items[].discounts` instead.
                metadata:
                  type: object
                  description: >-
                    Free-form string key/value pairs attached to the
                    subscription.
                trial_period_days:
                  type: integer
                  description: >-
                    Starts the subscription on a trial of this many days,
                    deferring the first recurring charge until the trial ends.
                    Must be a positive integer. What happens when the trial ends
                    is not configurable per request: OpenLoop sets the end
                    behaviour to `cancel`, so a trial that ends with no payment
                    method on file cancels the subscription rather than
                    invoicing it. `trial_settings` is not a request field — a
                    body that carries one is accepted and the field is ignored.
                on_session:
                  type: boolean
                  description: >-
                    Opts into the on-session (customer-present) payment posture:
                    the response then carries a `payment_confirmation` block
                    whose `client_secret` your browser confirms while the
                    customer is still present, which is what makes 3D Secure
                    reachable and can reduce first-payment declines. Absent or
                    `false` keeps the default off-session behavior unchanged,
                    including the error on a declined card. Must be a boolean
                    when supplied — a non-boolean value is rejected with a
                    `400`. **If you set `on_session: true` and the response
                    carries no `payment_confirmation` key, the posture was not
                    honored** — you are talking to a deployment that predates
                    this field, and the first charge has already been attempted
                    off-session. Do not proceed to browser confirmation in that
                    case.
              required:
                - provider_customer_id
                - items
            example:
              provider_customer_id: test_customer_id
              provider_payment_method_id: test_payment_method_id
              items:
                - provider_price_id: test_price_id
              on_session: false
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      config_id:
                        type: string
                        description: Configuration ID.
                      provider_account_id:
                        type:
                          - string
                          - 'null'
                        description: Provider account ID.
                      payment_provider:
                        type: string
                        description: Provider enum (e.g. `"stripe"`).
                      subscription:
                        type: object
                        properties:
                          provider_customer_id:
                            type: string
                            description: Provider customer ID owning the subscription.
                          provider_subscription_id:
                            type: string
                            description: Provider subscription ID.
                          status:
                            type: string
                            description: >-
                              Provider subscription status. A subscription
                              paused by OpenLoop reads `active` here, never
                              `paused` — detect a pause with the `paused` field.
                              A pause created before the current pause mechanism
                              still reports `status: "paused"`, so a correct
                              consumer treats `paused === true` **or** `status
                              === "paused"` as paused; neither alone covers both
                              populations.
                          description:
                            type:
                              - string
                              - 'null'
                            description: Subscription description.
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                provider_item_id:
                                  type: string
                                  description: Provider subscription-item ID.
                                quantity:
                                  type: number
                                  description: Item quantity.
                                metadata:
                                  type:
                                    - object
                                    - 'null'
                                  description: >-
                                    Custom metadata (string key/value pairs) or
                                    `null`.
                                price:
                                  type:
                                    - object
                                    - 'null'
                                  properties:
                                    provider_price_id:
                                      type: string
                                      description: Provider price ID.
                                    provider_product_id:
                                      type: string
                                      description: Provider product ID.
                                    currency:
                                      type: string
                                      description: ISO 4217 currency code.
                                    amount_cents:
                                      type: number
                                      description: Unit amount in cents.
                                    active:
                                      type:
                                        - boolean
                                        - 'null'
                                      description: >-
                                        Whether the price is still active;
                                        `false` when the subscription sits on a
                                        retired price. `null` when the provider
                                        omits it — treat that as unknown, not as
                                        retired.
                                    billing_scheme:
                                      type:
                                        - string
                                        - 'null'
                                      description: >-
                                        `per_unit` or `tiered`; `null` when the
                                        provider omits it.
                                    created:
                                      type:
                                        - number
                                        - 'null'
                                      description: Unix timestamp the price was created.
                                    recurring:
                                      type:
                                        - object
                                        - 'null'
                                      properties:
                                        interval:
                                          type: string
                                          description: Billing interval (e.g. `"month"`).
                                        interval_count:
                                          type: number
                                          description: Number of intervals per billing cycle.
                                      description: >-
                                        Recurring interval details or `null` for
                                        one-time prices.
                                  description: Price details or `null`.
                                product:
                                  type:
                                    - object
                                    - 'null'
                                  properties:
                                    name:
                                      type: string
                                      description: Product name.
                                    description:
                                      type:
                                        - string
                                        - 'null'
                                      description: Product description.
                                    metadata:
                                      type: object
                                      description: >-
                                        Custom metadata (string key/value
                                        pairs).
                                  description: Product details or `null`.
                                current_period_start:
                                  type:
                                    - number
                                    - 'null'
                                  description: Unix timestamp of the current period start.
                                current_period_end:
                                  type:
                                    - number
                                    - 'null'
                                  description: Unix timestamp of the current period end.
                                created:
                                  type:
                                    - number
                                    - 'null'
                                  description: Unix timestamp the item was created.
                                discounts:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      provider_discount_id:
                                        type: string
                                        description: Provider discount ID.
                                      provider_coupon_id:
                                        type:
                                          - string
                                          - 'null'
                                        description: >-
                                          Provider coupon ID backing this
                                          discount, or `null`.
                                      provider_promotion_code_id:
                                        type:
                                          - string
                                          - 'null'
                                        description: >-
                                          Provider promotion code ID that created
                                          this discount, or `null` when a coupon
                                          was applied directly.
                                      start:
                                        type:
                                          - number
                                          - 'null'
                                        description: Unix timestamp the discount started.
                                      end:
                                        type:
                                          - number
                                          - 'null'
                                        description: >-
                                          Unix timestamp the discount ends, or
                                          `null` if open-ended.
                                  description: >-
                                    Discounts applied to this item only,
                                    separate from the subscription-level
                                    `discounts`. Empty array when none.
                            description: Subscription items.
                          cancellation_details:
                            type:
                              - object
                              - 'null'
                            properties:
                              comment:
                                type:
                                  - string
                                  - 'null'
                                description: Cancellation comment.
                              feedback:
                                type:
                                  - string
                                  - 'null'
                                description: Cancellation feedback code.
                              reason:
                                type:
                                  - string
                                  - 'null'
                                description: Cancellation reason.
                            description: Cancellation metadata or `null`.
                          discounts:
                            type: array
                            items:
                              type: object
                              properties:
                                provider_discount_id:
                                  type: string
                                  description: Provider discount ID.
                                provider_coupon_id:
                                  type:
                                    - string
                                    - 'null'
                                  description: >-
                                    Provider coupon ID backing this discount, or
                                    `null`. Resolve its economics with `GET
                                    /coupons/{provider_coupon_id}` — discounts
                                    themselves cannot be fetched by ID.
                                provider_promotion_code_id:
                                  type:
                                    - string
                                    - 'null'
                                  description: >-
                                    Provider promotion code ID that created this
                                    discount, or `null` when a coupon was
                                    applied directly. Resolve it with `GET
                                    /promotion-codes` filtered by
                                    `provider_coupon_id` — there is no
                                    fetch-by-ID for promotion codes.
                                start:
                                  type:
                                    - number
                                    - 'null'
                                  description: Unix timestamp the discount started.
                                end:
                                  type:
                                    - number
                                    - 'null'
                                  description: >-
                                    Unix timestamp the discount ends; `null` for
                                    `once` and `forever` coupons.
                            description: >-
                              Discounts currently applied to the subscription.
                              Empty array when none.
                          cancel_at_period_end:
                            type: boolean
                            description: Whether the subscription cancels at period end.
                          cancel_at:
                            type:
                              - number
                              - 'null'
                            description: >-
                              Unix timestamp the subscription is scheduled to
                              cancel.
                          canceled_at:
                            type:
                              - number
                              - 'null'
                            description: Unix timestamp the subscription was canceled.
                          ended_at:
                            type:
                              - number
                              - 'null'
                            description: Unix timestamp the subscription ended.
                          paused:
                            type: boolean
                            description: >-
                              Whether a pause is currently in effect **and the
                              subscription is still running**. A terminal
                              subscription (`canceled` / `incomplete_expired`)
                              reads `false` even if a leftover pause remains.
                          resumes_at:
                            type:
                              - number
                              - 'null'
                            description: >-
                              Unix timestamp the pause lifts itself; `null` when
                              the pause is open-ended, the subscription is not
                              paused, or the subscription is terminal.
                          metadata:
                            type: object
                            additionalProperties:
                              type: string
                            description: >-
                              Free-form string key/value pairs attached to the
                              subscription.
                          start_date:
                            type: number
                            description: Unix timestamp the subscription started.
                          trial_start:
                            type:
                              - number
                              - 'null'
                            description: Unix timestamp the trial started.
                          trial_end:
                            type:
                              - number
                              - 'null'
                            description: Unix timestamp the trial ends/ended.
                          collection_method:
                            type: string
                            description: '`charge_automatically` or `send_invoice`.'
                          created:
                            type:
                              - number
                              - 'null'
                            description: Unix timestamp.
                          last_invoice:
                            type:
                              - object
                              - 'null'
                            properties:
                              provider_invoice_id:
                                type: string
                                description: Provider invoice ID.
                              created:
                                type:
                                  - number
                                  - 'null'
                                description: Unix timestamp the invoice was created.
                            description: Last invoice reference or `null`.
                          provider_payment_method_id:
                            type:
                              - string
                              - 'null'
                            description: >-
                              Payment-method id that paid the latest invoice.
                              When no payment method paid it (for example during
                              a trial, or when the invoice was settled from
                              credit balance), the payment method the payment
                              provider will charge next: the subscription's
                              default, otherwise the billing customer's invoice
                              default. `null` when none is set.
                          billing_cycle_anchor:
                            type: number
                            description: >-
                              Unix timestamp the subscription's billing cycles
                              are anchored to.
                        description: Fields documented in the sub-table below.
                      payment_confirmation:
                        type: object
                        properties:
                          status:
                            type: string
                            description: >-
                              `requires_confirmation` — the first invoice needs
                              the customer to confirm payment; `client_secret`
                              carries the secret to do it with. `not_required` —
                              there was nothing to confirm (e.g. a `$0` trial or
                              fully-discounted first invoice), and the
                              subscription starts `active` or `trialing`. Branch
                              on this field rather than on whether
                              `client_secret` is `null`. A card declined at
                              confirmation leaves the PaymentIntent at
                              `requires_payment_method` and the subscription
                              `incomplete`: collect a replacement payment method
                              and confirm the **same** PaymentIntent again — do
                              not create a second subscription.
                          client_secret:
                            type:
                              - string
                              - 'null'
                            description: >-
                              The first invoice's PaymentIntent client secret,
                              used to confirm the payment client-side (e.g.
                              Stripe's `confirmPayment`). `null` when `status`
                              is `not_required`. Scoped to this one payment only
                              — it does not grant broader account access.
                        description: >-
                          Present only when the request set `on_session: true` —
                          omitted entirely otherwise, so an off-session response
                          is unchanged. **A `200` on this posture does not mean
                          the customer has paid**: the subscription comes back
                          `incomplete` and its first invoice is unpaid until the
                          client confirms `client_secret`. Gate provisioning on
                          the invoice-settled webhook, never on this response.
                          An unconfirmed subscription transitions itself to
                          `incomplete_expired` in under a day and its initial
                          invoice is voided — that state is terminal, so create
                          a new subscription rather than retrying it. Treat the
                          status as the signal, not a clock; the exact window is
                          the provider's to change.
                required:
                  - data
              example:
                data:
                  config_id: test_config_id
                  provider_account_id: test_account_id
                  payment_provider: stripe
                  subscription:
                    provider_customer_id: test_customer_id
                    provider_subscription_id: test_subscription_id
                    status: active
                    description: null
                    items:
                      - provider_item_id: test_subscription_item_id
                        quantity: 1
                        metadata: null
                        price: null
                        product: null
                        current_period_end: 1700
                        current_period_start: 1300
                        created: 1300
                        discounts: []
                    cancellation_details: null
                    discounts: []
                    cancel_at_period_end: false
                    cancel_at: null
                    canceled_at: null
                    ended_at: null
                    paused: false
                    resumes_at: null
                    metadata: {}
                    start_date: 1300
                    trial_start: null
                    trial_end: null
                    collection_method: charge_automatically
                    created: 1300
                    last_invoice:
                      provider_invoice_id: test_invoice_id
                      created: 1300
                    provider_payment_method_id: test_payment_method_id
                    billing_cycle_anchor: 1300
        '400':
          description: >-
            ValidationError: A body carrying the removed `one_time_items` array
            (`one_time_items is no longer supported; send one-time prices in
            items` — checked first, before any other body validation, so a
            request written against the older shape is told exactly that);
            missing/empty `provider_customer_id`; `provider_payment_method_id`
            present but empty; empty `items`; an item without
            `provider_price_id`; non-positive/non-integer `quantity`; malformed
            `metadata`; an `items` array with no recurring price (`items must
            include at least one recurring price` — raised during the pre-create
            price lookup, so no subscription exists and nothing is charged); an
            `items` array with more than one recurring price (`A subscription
            can have only one recurring price. Create a separate subscription
            for each recurring product.` — raised by the same lookup, with the
            same guarantee); `trial_period_days` not a positive integer;
            `on_session` present but not a boolean; **no
            `provider_payment_method_id` supplied and the customer has no
            default payment method, on the off-session posture only** — not
            raised when `on_session: true`; the provider customer has been
            deleted, on both postures, **when no `provider_payment_method_id`
            was supplied** (supply one and the provider rejects the deleted
            customer instead); `discounts` (or an `items[].discounts`) that is
            not an array (`discounts must be an array`); a `discounts` entry
            that is not an object (`discounts entries must be objects with
            exactly one of coupon, promotion_code or discount`); a `discounts`
            entry carrying two or more of `coupon`, `promotion_code` and
            `discount` as non-empty strings, or none of them (`each discount
            entry must specify exactly one of coupon, promotion_code or
            discount`). ProviderError: the payment provider's own validation
            rejections, such as a payment method not attached to the customer;
            and, **on the off-session posture only**, a failed off-session
            charge (card declined or authentication required), returned with
            `error_code` `PROVIDER_ERROR`, after which no `incomplete`
            subscription is created. On the on-session posture the card is not
            charged during the request, so a decline surfaces client-side after
            a `200`.
        '401':
          description: Missing or invalid bearer token.
        '403':
          description: >-
            No configuration exists for your account, or provider access has
            been disabled for it.
        '404':
          description: >-
            NotFoundError: Referenced customer not found in your account. Also
            an `items` entry whose `provider_price_id` the provider does not
            have (`items price not found: <id>`) — raised during the pre-create
            price lookup, so no subscription exists and nothing is charged. If
            several ids are unresolvable, all of them are named in the one
            response.
        '500':
          description: >-
            Payment provider integration error. The provider's own validation
            rejections (such as a payment method not attached to the customer)
            are a `400`, and an unknown `provider_price_id` is a `404`, not a
            `500`.
      security:
        - serviceToken: []
        - userToken: []
components:
  securitySchemes:
    serviceToken:
      type: oauth2
      description: >-
        Service (M2M) access token issued by POST /auth/token using the
        client_credentials grant. Required scopes, where known, are listed on
        each operation below.
      flows:
        clientCredentials:
          tokenUrl: https://api.openloophealth.com/v0.1/auth/token
          scopes: {}
    userToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        User access token issued by POST /auth/token via the verification-code
        grant (after Verify a one-time code) or the refresh_token grant.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.