openapi: 3.1.0
info:
  title: Storefront Subscriptions
  version: 1.0.0
paths:
  /subscriptions:
    post:
      operationId: createSubscription
      summary: Create Subscription
      description: >-
        Creates or updates an email subscription.


        By default, customers receive abandoned cart emails as soon as they provide their email address in the checkout
        flow. They can opt out using this endpoint.


        However, if **Store Settings > Miscellaneous > Require Consent** is enabled, Abandoned Cart Emails are not sent
        by default, and the customer should opt-in.


        > #### Note

        > * Substitute your storefront domain for `yourstore.example.com`. 

        > * The Send a Test Request feature is not currently supported for this endpoint.
      tags:
        - subscription
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
servers:
  - url: https://your_store.example.com/api/storefront
    description: https://{store_domain}/api/storefront
components:
  schemas:
    SubscriptionRequest:
      type: object
      properties:
        email:
          type: string
          description: Email of subscriber
        acceptsMarketingNewsletter:
          type: boolean
          description: Describes whether subscriber has consented to receive Marketing emails.
        acceptsAbandonedCartEmails:
          type: boolean
          description: Describes whether subscriber has consented to receive Abandoned Cart emails.
      title: SubscriptionRequest
    Subscription:
      type: object
      properties:
        id:
          type: integer
          description: |
            The unique numeric ID of the subscriber; increments sequentially.
        email:
          type: string
          description: |
            The email of the subscriber. Must be unique.
        firstName:
          type: string
          description: |
            The first name of the subscriber.
        lastName:
          type: string
          description: |
            The last name of the subscriber.
        source:
          type: string
          description: |
            The source of the subscriber. Values are: `storefront`, `order`, or `custom`.
        orderId:
          type:
            - integer
            - 'null'
          description: |
            The ID of the source order, if source was an order.
        consents:
          type: array
          items:
            description: Any type
          description: |
            The collection of consents the shopper is subscribing to.
      description: Subscription properties.
      title: Subscription
