Elastic Path Flows API

openapi: 3.2.0
info:
  title: Service Introduction Flows API
  version: 25.1201.6902711
  x-version-timestamp: 2025-12-01 12:04:04+00:00
  description: "\nWith flows you can extend the capabilities of Commerce and Product Experience Manager at both organization and store level, and apply Composable Commerce to almost any use case.\n \n### Flows in Commerce\n \nYou can define custom data fields for the resources that you use in your store or organization, such as adding more fields to the `customer` resource. \n \n You can also create new resources, such as a `wishlist` resource to support wishlists in your store. \n \n:::note\n \n [Custom APIs](/docs/api/commerce-extensions/custom-ap-is#custom-apis-vs-non-core-flows) are the next generation of Non-Core Flows. Flows are not going anywhere, but Custom APIs offer enhanced capabilities. We recommend using Custom APIs for any of your new use cases.\n \n:::\n\n:::caution\n \n- In an organization, not all resources are available. See [**Extend a resource**](https://elasticpath.dev/guides/Custom%20Data/extend-any-resource) for a list of organization resources that can be extended.\n- If you store any sensitive Personal Identifiable Information (PII) or non-public data on your site, ensure that you do not use this data in flows to avoid potential unauthorized access to the data. For more information, see [**Permissions**](/docs/authentication/tokens/permissions).\n \n:::\n \n### Templates in Product Experience Manager\n \n Templates allow you to attach a specific set of attributes to your products.\n \n - You can use templates to define characteristics of your product, for example, a product specification. For example, a *Book* template might contain attributes, such as *ISBN*, *Author*, *Number of pages*, *Year Published*, or *Condition (New/Used)*.\n - You can use templates for Search Engine Optimization (SEO). When you assign template attributes such as, *care instructions* or *fabric*, to a shirt and a shopper searches for a specific item, attributes help stores to return the products that match the search criteria. For example, when a shopper searches for a large blue shirt, all shirts that are large and blue are returned in the search result.\n"
servers:
- url: https://euwest.api.elasticpath.com
  description: EU West Production Server
- url: https://useast.api.elasticpath.com
  description: US East Production Server
security:
- bearerAuth: []
tags:
- name: Flows
  description: "\n### Flows in Commerce\n\nThere are two scenarios for using flows:\n\n- Extend an existing resource, such as customers and orders.\n- Create a new resource, such as a blog, wishlist, or customer review.\n\n#### Extend an existing resource\n\nThe most common usage of the Flows API is to extend existing resources, such as `customers` and `orders`. These types of resources are called core flows and are handled differently than non-core flows. See [**Core and non-core flows**](#core-and-non-core-flows).\n\nFor example, you can extend the `customer` resource to store custom data, such as a `user_profile` field for customers. Or you might want to add an `age` field to store a customer's age.\n\nExtending a resource applies only to core flows. When creating a new flow, make sure the `slug` matches that of a core resource listed in the following table.\n\n| Flow slug                                   | Description                    | Availability Level |\n|:--------------------------------------------|:-------------------------------| :---|\n| `accounts`                                  | Extend the [`account`](/docs/api/accounts/account-management-introduction) object. | Store |\n| `account-members`                           | Extend the [`account-members`](/docs/api/accounts/account-members) object. | Store |\n| `account-memberships`                       | Extend the [`account-membership`](/docs/api/accounts/account-membership) object. | Store |\n| `addresses`                                 | Extend the [`address`](/docs/api/addresses/account-addresses) object. | Store |\n| `authentication-realms`                     | Extend the [`authentication-realms`](/docs/api/single-sign-on/authentication-realms) object. | Store |\n| `carts`                                     | Extend the [`carts`](/docs/api/carts/carts-checkout-orders-introduction) object. | Organization/Store |\n| `cart_items`                                | Extend the [`cart_item`](/docs/api/carts/cart-items) object. | Organization/Store |\n| `customers`                                 | Extend the [`customer`](/docs/customer-management/customer-management-api/customer-management-api-overview) object. **Note**: Please use Account Management for all new frontend experiences.  | n/a |\n| `oidc-profiles`                             | Extend the [`oidc-profiles`](/docs/api/single-sign-on/oidc-profiles) object. | Store |\n| `order_items`                               | Extend the [`order_item`](/docs/api/carts/get-order-items) object. | Organization/Store |\n| `orders`                                    | Extend the [`order`](/docs/api/carts/orders) object. | Organization/Store |\n| `password-profiles`                         | Extend the [`password-profiles`](/docs/api/single-sign-on/password-profiles) object. | Store |\n| `products`                                  | Extend the [`product`](/docs/api/pxm/products/products) object. | Store |\n| `promotions`                                | Extend the [`promotion`](/docs/api/promotions/promotions-standard-introduction) object. | Store |\n| `rule-promotions`                           | Extend the [`rule-promotion`](/docs/api/promotions-builder/create-rule-promotion) object. | Store |\n| `user-authentication-info`                  | Extend the [`user-authentication-info`](/docs/api/single-sign-on/user-authentication-infos) object. | Store |\n| `user-authentication-oidc-profile-info`     | Extend the [`user-authentication-oidc-profile-info`](/docs/api/single-sign-on/user-authentication-oidc-profile-infos) object. | Store |\n| `user-authentication-password-profile-info` | Extend the [`user-authentication-password-profile-info`](/docs/api/single-sign-on/user-authentication-password-profile-infos) object. | Store |\n| `catalogs`                                  | Extend the [`catalog`](/docs/api/pxm/catalog/catalogs) object. It will not extend the [`catalog-release`](/docs/api/pxm/catalog/releases) object. | Store |\n\n#### Create a new resource\n\nYou can create new resources to support product reviews, wish lists, blog articles, staff profile pages, and many more. These non-core flows are referred to as custom flows. See [**Core and non-core flows**](#core-and-non-core-flows).\n\n:::note\n\n[Custom APIs](/docs/api/commerce-extensions/custom-ap-is#custom-apis-vs-non-core-flows) are the next generation of Non-Core Flows. Flows are not going anywhere, but Custom APIs offer enhanced capabilities. We recommend using Custom APIs for any of your new use cases.\n\n:::\n\n#### Core and non-core flows\n\nThe following table describes the differences between core and non-core flows:\n\n| Core Flows                                                    | Non-core Flows |\n|:--------------------------------------------------------------|:-------------|\n| Extend an existing resource.                                  | Create a new resource. |\n| Entries managed automatically by Commerce. | Create and manage entries manually. |\n| Requests are sent to the `fields` endpoint.                   | Requests are sent to the `entries` endpoint. |\n\n:::caution\n\nYou cannot delete core flows after creating them with the API or Commerce Manager.\n\n:::\n\n#### Flows taxonomy\n\nFields and entries are an integral part of flows. A flow describes a collection of fields. A field represents a single field of data. An entry is a specific instance of a flow, and is associated with a specific instance of an entity, such as a single customer. Entries for core flows (existing resources) are managed automatically for you.\n\nIn database terms, you can think of flows as tables, fields as columns, and entries as database records.\n\n### Templates in Product Experience Manager\n\nTemplates allow you to attach a specific set of attributes to your products.\n\n- You can use templates to define characteristics of your products.\n- You can use templates for Search Engine Optimization (SEO).\n\n#### Template Taxonomy\n\nAttributes and entries are integral to templates. A template describes a collection of attributes. An attribute represents a single characteristic, like color. An entry is a specific instance of an attribute, for example, blue, and is associated with a specific product.\n\n  A template is exactly the same as a flow except it has a different naming convention. The name of a template is in the format **products(*slug*)** where *slug* is the slug of a template.\n\n#### Associating templates with products\n\n  Once you have created your template, and [**associated**](/docs/api/flows/create-an-entry-relationship) the temp with a product in Product Experience Manager, it becomes a template. \n\n  For example, if you create a template with a slug of `SizeGuide` then the template name is **products(SizeGuide)**. You can then [**associate**](/docs/api/flows/create-an-entry-relationship) this template to all clothing products in your store and the slug is included in all the responses that contain products.\n\n   You can create product templates for both organization and store. In addition, stores can use organization templates for store-level products.\n\n  For more information about adding attributes, see [**Fields**](/docs/api/flows/fields).\n"
paths:
  /v2/flows:
    get:
      tags:
      - Flows
      summary: Get all Flows
      description: '- For Commerce, this endpoint retrieves a list of flows.

        - For Product Experience Manager, this endpoint retrieves a list of templates.

        '
      operationId: getAllFlows
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Flows'
              examples:
                default:
                  value:
                    data:
                    - id: 6d320b42-237d-4474-8452-d49f884d4ae1
                      type: flow
                      name: Products-1
                      slug: products-1
                      description: Extends the default product object
                      enabled: true
                      links:
                        self: https://useast.api.elasticpath.com/v2/flows/6d320b42-237d-4474-8452-d49f884d4ae1
                      relationships: {}
                      meta:
                        owner: organization
                        timestamps:
                          created_at: '2018-05-10T18:04:26.623Z'
                          updated_at: '2018-05-10T18:04:26.623Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Flows
      summary: Create a Flow
      description: '- For Commerce, this endpoint creates a flow.

        - For Product Experience Manager, this endpoint creates a template.


        :::caution


        Custom names and values prefixed with $ are not supported.


        :::

        '
      operationId: createAFlow
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/FlowsRequest'
              - examples:
                - data:
                    description: Extends the default product object
                    enabled: true
                    name: Products
                    slug: products
                    type: flow
              contentMediaType: application/json
            examples:
              default:
                value:
                  data:
                    description: Extends the default product object
                    enabled: true
                    name: Products
                    slug: products
                    type: flow
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Flows'
              examples:
                default:
                  value:
                    data:
                      id: 6d320b42-237d-4474-8452-d49f884d4ae1
                      type: flow
                      name: Products-1
                      slug: products-1
                      description: Extends the default product object
                      enabled: true
                      links:
                        self: https://useast.api.elasticpath.com/v2/flows/6d320b42-237d-4474-8452-d49f884d4ae1
                      relationships: {}
                      meta:
                        owner: organization
                        timestamps:
                          created_at: '2018-05-10T18:04:26.623Z'
                          updated_at: '2018-05-10T18:04:26.623Z'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/flows/{flowID}:
    get:
      tags:
      - Flows
      summary: Get a Flow
      description: '- For Commerce, this endpoint retrieves a flow.

        - For Product Experience Manager, this endpoint retrieves a template.

        '
      operationId: getAFlow
      parameters:
      - name: flowID
        description: The unique identifier of the flow/template you want to retrieve.
        in: path
        required: true
        style: simple
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Flows'
              examples:
                default:
                  value:
                    data:
                      id: 38ba1451-efa4-4361-9ca6-3fb646490f37
                      type: flow
                      name: extraFieldRenamed
                      slug: products
                      description: Extends the default product object
                      enabled: true
                      links:
                        self: https://useast.api.elasticpath.com/v2/flows/38ba1451-efa4-4361-9ca6-3fb646490f37
                      relationships: {}
                      meta:
                        owner: organization
                        timestamps:
                          created_at: '2018-05-10T01:41:36.009Z'
                          updated_at: '2018-05-10T15:27:26.241Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Flows
      summary: Delete a Flow
      description: '- For Commerce, this endpoint deletes a flow. We recommend that you remove all the fields assigned to a flow before deleting a flow.

        - For Product Experience Manager, this endpoint deletes a template. We recommend that you remove all the attributes assigned to a template before deleting a template.

        '
      operationId: deleteAFlow
      parameters:
      - name: flowID
        description: The unique identifier of the flow/template you want to delete.
        in: path
        required: true
        style: simple
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Flows
      summary: Update a Flow
      description: "- For Commerce, this endpoint updates a flow. \n- For Product Experience Manager, this endpoint updates a template. \n\n Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the flow/template is not updated.\n"
      operationId: updateAFlow
      parameters:
      - name: flowID
        description: The unique identifier of the flow/template you want to update.
        in: path
        required: true
        style: simple
        schema:
          $ref: '#/components/schemas/UUID'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/FlowsUpdateRequest'
              contentMediaType: application/json
            examples:
              default:
                value:
                  data:
                    id: 25617d3e-14a6-434c-bfab-3fda87517aaf
                    description: Extends the default product object
                    enabled: true
                    name: Products
                    slug: products
                    type: flow
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Flows'
              examples:
                default:
                  value:
                    data:
                      id: 6d320b42-237d-4474-8452-d49f884d4ae1
                      type: flow
                      name: extraFieldRenamed
                      slug: products-1
                      description: Extends the default product object
                      enabled: true
                      links:
                        self: https://useast.api.elasticpath.com/v2/flows/6d320b42-237d-4474-8452-d49f884d4ae1
                      relationships: {}
                      meta:
                        owner: store
                        timestamps:
                          created_at: '2018-05-10T18:04:26.623Z'
                          updated_at: '2018-05-10T18:11:47.469Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    FlowsUpdateRequest:
      title: FlowsUpdateRequest
      type: object
      properties:
        data:
          type: object
          properties:
            description:
              type: string
              description: A brief description of a flow/template outlining details such as purpose, usage instructions, and so on.
              examples:
              - Extends the default product object
            enabled:
              type: boolean
              examples:
              - true
            name:
              type: string
              description: The name of a flow/template.
              examples:
              - Products
            id:
              $ref: '#/components/schemas/UUID'
            slug:
              type: string
              description: A unique slug identifier for a flow/template.
              examples:
              - products
            type:
              type: string
              description: Represents the type of object being returned.
              examples:
              - flow
    Meta:
      type: object
      properties:
        owner:
          type: string
          description: The resource owner, either `organization` or `store`.
          example: enum
          enum:
          - store
          - organization
        timestamps:
          type: object
          properties:
            created_at:
              type: string
              description: The date and time a resource is created.
              example: '2023-10-11T13:02:25.293Z'
            updated_at:
              type: string
              description: The date and time a resource is updated.
              example: '2023-10-11T13:02:25.293Z'
    ErrorResponse:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    FlowsRelationships:
      type: object
      description: Relationships are established between different flows/templates entities. For example, a field and an entry are related to a flow as both are attached to it.
      properties:
        fields:
          type: object
          properties:
            data:
              $ref: '#/components/schemas/Relationships'
    FlowsRequest:
      title: FlowsRequest
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          - name
          - slug
          - enabled
          - description
          properties:
            description:
              type: string
              description: A brief description of a flow/template outlining details such as purpose, usage instructions and so on.
              examples:
              - A flow to extend the `customer` resource.
              - A SizeGuide template for the clothing that we sell.
            enabled:
              type: boolean
              examples:
              - true
            name:
              type: string
              description: The name of a flow/template.
              examples:
              - Products
            slug:
              type: string
              description: A unique slug identifier for a flow/template.
              examples:
              - products
            type:
              type: string
              description: Represents the type of object being returned.
              examples:
              - flow
    FlowsLinks:
      type: object
      description: "Links allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Listing pages use the following:\n \n | Property | Description |\n | --- | --- |\n | `current` | Always the current page |\n | `first` | Always the first page |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if you are on the first page. |\n | `next` | `null` if there is only one page. |\n"
      properties:
        self:
          type: string
          example: https://euwest.api.elasticpath.com/v2/flows/d2a9b22a-b4b0-456b-bbc7-d8723aaffa84
    Flows:
      title: Flows
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          type: string
          description: A unique identifier for a flow/template.
          example: flow
        name:
          type: string
          description: The name of a flow/template.
          example: Products
        slug:
          type: string
          description: A unique identifier of a flow/template.
          example: products
        description:
          type: string
          description: A short description for a flow/template.
          example: Extends the default product object
        enabled:
          type: boolean
          example: true
        links:
          $ref: '#/components/schemas/FlowsLinks'
        relationships:
          $ref: '#/components/schemas/FlowsRelationships'
        meta:
          $ref: '#/components/schemas/Meta'
    Relationships:
      title: Relationships
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          type: string
          description: Represents the type of object being returned.
          example: brand
    Error:
      required:
      - status
      - title
      properties:
        status:
          type: integer
          format: int
          description: The HTTP response code of the error.
          example: 500
        title:
          type: string
          description: A brief summary of the error.
          example: Internal server error
        detail:
          type: string
          description: Optional additional detail about the error.
          example: An internal error has occurred.
        request_id:
          type: string
          description: Internal request ID.
          example: 00000000-0000-0000-0000-000000000000
        meta:
          type: object
          description: Additional supporting meta data for the error.
          example:
            missing_ids:
            - e7d50bd5-1833-43c0-9848-f9d325b08be8
    UUID:
      type: string
      description: A unique identifier for a resource.
      format: uuid
      example: 00000000-0000-0000-0000-000000000000
  responses:
    NotFound:
      description: Bad request. Not Found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              value:
                errors:
                - title: Not Found
                  status: 404
    ValidationError:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing-name:
              value:
                errors:
                - title: Validation Error
                  status: 400
                  detail: 'data.attributes.name: "name" is required'
    InternalServerError:
      description: Internal server error. There was a system failure in the platform.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              value:
                errors:
                - status: 500
                  title: Internal Server Error
                  detail: There was an internal server error, you can report with your request id.
                  request_id: 635da56d-75a1-43cd-b696-7ab119756b3a
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer