Elastic Path Fields API

openapi: 3.2.0
info:
  title: Flows Service Introduction Fields 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: Fields
  description: "With fields, you can:\n\n- in Commerce, use a field in your flows to represent  single field of data (for example a `Product Rating`) to be applied to an entity\n- in Product Experience Manager, use an attribute in your template to attach a characteristic like `color` to a product.\n\nA field/attribute represents a single piece of data. All fields/attributes have a `field_type` (`string`, `integer`, `boolean`, `date` or `relationship`), a default value, and an optional set of validation rules.\n\n:::caution\n\n- Custom names and values prefixed with `$` are not supported.\n- There is a hard limit of 100 fields per flow.\n- You can configure default values for fields. If you choose to do so, you must ensure that your default field values comply with your validation rules.\n\n:::\n\n#### Field/Attribute Validation Rules\n\nWhen creating a field/attribute, you can add validation to the values that are stored. The validation you use depends on the `field_type` of the field/attribute. Each validation rule is expressed as a validation rule object.\n\n#### `string` / `enum`\n\nMust be one of a predefined collection of strings. If you leave the field blank or enter an incorrect value then an `Invalid Value` error is displayed. \n\n| Attribute | Type | Description |\n| :--- | :--- | :--- |\n| `type` | `string` | `enum` |\n| `options` | `array[string]` | An array of valid string values. |\n\n##### `string` / `email`\n\nMust be a valid email address.\n\n| Attribute | Type | Description |\n| :--- | :--- | :--- |\n| `type` | `string` | `email` |\n\n##### `string` / `slug`\n\nCan contain only letters, numbers, hyphens and underscores.\n\n| Attribute | Type | Description |\n| :--- | :--- | :--- |\n| `type` | `string` | `slug` |\n\n##### `integer` / `between`\n\nMust be between the two provided values.\n\n| Attribute | Type | Description |\n| :--- | :--- | :--- |\n| `type` | `string` | `enum` |\n| `options` | `object` | An object containing `from` and `to` integers. |\n\n##### `integer` / `enum`\n\nMust be one of a predefined collection of integers.\n\n| Attribute | Type | Description |\n| :--- | :--- | :--- |\n| `type` | `string` | `enum` |\n| `options` | `array[integer]` | An array of valid integer values. |\n\n##### `float` / `between`\n\nMust be between the two provided values.\n\n| Attribute | Type | Description |\n| :--- | :--- | :--- |\n| `type` | `string` | `enum` |\n| `options` | `object` | An object containing `from` and `to` floats. |\n\n##### `float` / `enum`\n\nMust be one of a predefined collection of floats.\n\n| Attribute | Type | Description |\n| :--- | :--- | :--- |\n| `type` | `string` | `enum` |\n| `options` | `array[float]` | An array of valid float values. |\n\n#### `date` / `enum`\n\nMust be one of a predefined collection of dates.\n\n| Attribute | Type | Description |\n| :--- | :--- | :--- |\n| `type` | `string` | `enum` |\n| `options` | `array[string]` | An array of valid date values as strings \\(`YYYY-MM-DD HH:MM:SS` - time is optional\\). |\n\n##### `relationship` / `one-to-many`\n\n:::caution\nThis only applies to Commerce. You cannot use relationships in Product Experience Manager templates.\n:::\n\nAllows multiple relationships to be created.\n\n| Attribute | Type | Description |\n| :--- | :--- | :--- |\n| `type` | `string` | `one-to-many` |\n| `to` | `string` | The entity type you are making relationships with in singular form (for example, `product`). |\n\n##### `relationship` / `one-to-one`\n\n:::caution\nThis only applies to Commerce. You cannot use relationships in Product Experience Manager templates.\n:::\n\nAllows only a single relationships to be created on an entry.\n\n| Attribute | Type | Description |\n| :--- | :--- | :--- |\n| `type` | `string` | `one-to-one` |\n| `to` | `string` | The entity type you are making relationships with in singular form (for example, `customer`). |\n"
paths:
  /v2/fields:
    get:
      tags:
      - Fields
      summary: Get all Fields
      description: "- For Commerce, this endpoint retrieves all fields in a flow. \n- For Product Experience Manager, this endpoint retrieves all attributes in a template.\n"
      operationId: getAllFields
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Field'
              examples:
                default:
                  value:
                    data:
                    - id: e88d03d3-d46e-40d0-8302-25e6b5b1bd33
                      type: field
                      field_type: boolean
                      slug: on_sale
                      name: On Sale?
                      description: Is this on sale?
                      required: false
                      default: null
                      enabled: true
                      order: null
                      omit_null: false
                      validation_rules: []
                      links:
                        self: https://useast.api.elasticpath.com/v2/flows/9d69c6cf-aaee-4dc6-8908-d2bd053446a2/fields/e88d03d3-d46e-40d0-8302-25e6b5b1bd33
                      relationships:
                        flow:
                          data:
                            id: 9d69c6cf-aaee-4dc6-8908-d2bd053446a2
                            type: flow
                      meta:
                        owner: organization
                        timestamps:
                          created_at: '2018-08-23T10:28:43.609Z'
                          updated_at: '2018-08-23T10:28:43.609Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Fields
      summary: Create a Field
      description: '- For Commerce, this endpoint creates a field.

        - For Product Experience Manager, this endpoint creates an attribute.

        '
      operationId: createAField
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/FieldRequest'
              contentMediaType: application/json
            examples:
              default:
                value:
                  data:
                    default: 4
                    description: Average rating as given by our users
                    enabled: true
                    field_type: integer
                    name: Product Rating
                    order: 1
                    relationships:
                      flow:
                        data:
                          id: '{{flowID}}'
                          type: flow
                    required: false
                    slug: product-rating
                    type: field
                    validation_rules:
                    - options:
                        from: 1
                        to: 5
                      type: between
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Field'
              examples:
                default:
                  value:
                    data:
                      type: field
                      name: Product Rating
                      slug: product-rating
                      field_type: integer
                      validation_rules:
                      - type: between
                        options:
                          from: 1
                          to: 5
                      description: Average rating as given by our users
                      required: false
                      default: 0
                      enabled: true
                      order: 1
                      omit_null: false
                      relationships:
                        flow:
                          data:
                            type: flow
                            id: e4145c27-aba1-46af-81a3-58f5e1cf7f15
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/fields/{flowFieldID}:
    get:
      tags:
      - Fields
      summary: Get a Field
      description: '- For Commerce, this endpoint retrieves a field.

        - For Product Experience Manager, this endpoint retrieves an attribute.

        '
      operationId: getAField
      parameters:
      - name: flowFieldID
        description: The unique identifier of the flow/template whose field/attribute you want to retrieve.
        in: path
        required: true
        style: simple
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Field'
              examples:
                default:
                  value:
                    data:
                      id: 102b2087-d56a-45e7-bf1c-e9517716abb3
                      type: field
                      field_type: integer
                      slug: product-rating
                      name: Product Rating
                      description: Average rating as given by our users
                      required: false
                      default: null
                      enabled: true
                      validation_rules:
                      - type: between
                        options:
                          from: 1
                          to: 5
                      order: 1
                      omit_null: false
                      links:
                        self: https://useast.api.elasticpath.com/v2/flows/6d320b42-237d-4474-8452-d49f884d4ae1/fields/102b2087-d56a-45e7-bf1c-e9517716abb3
                      relationships:
                        flow:
                          data:
                            id: 6d320b42-237d-4474-8452-d49f884d4ae1
                            type: flow
                      meta:
                        owner: organization
                        timestamps:
                          created_at: '2018-05-10T18:19:11.559Z'
                          updated_at: '2018-05-10T18:19:11.559Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Fields
      summary: Update a Field
      description: '- For Commerce, this endpoint updates a field.

        - For Product Experience Manager, this endpoint updates an attribute.


        Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the field/attribute is not updated.

        '
      operationId: updateAField
      parameters:
      - name: flowFieldID
        description: The unique identifier for the flow/template to which the field/attribute you want to update belongs.
        in: path
        required: true
        style: simple
        schema:
          $ref: '#/components/schemas/UUID'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/FieldUpdateRequest'
              contentMediaType: application/json
            examples:
              default:
                value:
                  data:
                    default: 1
                    description: Average rating as given by our users
                    field_type: integer
                    id: '{{flowFieldID}}'
                    name: Product Rating
                    required: true
                    enabled: true
                    slug: product-rating
                    type: field
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Field'
              examples:
                default:
                  value:
                    data:
                      id: 102b2087-d56a-45e7-bf1c-e9517716abb3
                      type: field
                      field_type: integer
                      slug: start-of-life
                      name: start-of-life
                      description: day the iphone will work
                      required: true
                      default: '2018-01-01'
                      enabled: true
                      validation_rules:
                      - type: between
                        options:
                          from: 1
                          to: 5
                      order: 1
                      omit_null: false
                      links:
                        self: https://useast.api.elasticpath.com/v2/flows/6d320b42-237d-4474-8452-d49f884d4ae1/fields/102b2087-d56a-45e7-bf1c-e9517716abb3
                      relationships:
                        flow:
                          data:
                            id: 6d320b42-237d-4474-8452-d49f884d4ae1
                            type: flow
                      meta:
                        owner: organization
                        timestamps:
                          created_at: '2018-05-10T18:19:11.559Z'
                          updated_at: '2018-05-10T18:36:01.208Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Fields
      summary: Delete a Field
      description: '- For Commerce, this endpoint deletes a field.

        - For Product Experience Manager, this endpoint deletes an attribute.

        '
      operationId: deleteAField
      parameters:
      - name: flowFieldID
        description: The unique identifier of the field/attribute that you want to delete.
        in: path
        required: true
        style: simple
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/flows/{flowSlug}/fields:
    get:
      tags:
      - Fields
      summary: Get all Fields by Flow
      description: Get all Fields by Flow
      operationId: getAllFieldsByFlow
      parameters:
      - name: flowSlug
        in: path
        required: true
        description: The slug of the flow the entry belongs to.
        style: simple
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Field'
              examples:
                default:
                  value:
                    data:
                    - id: 23d26fd2-d2e2-4c72-b4b4-3ef7a31bc47f
                      type: field
                      field_type: string
                      slug: background_color
                      name: background colors
                      description: background color for the product
                      required: false
                      default: '#ffffff'
                      enabled: true
                      validation_rules: []
                      order: null
                      omit_null: false
                      links:
                        self: https://useast.api.elasticpath.com/v2/flows/248c7776-bd9f-4075-8980-461b02ed3757/fields/23d26fd2-d2e2-4c72-b4b4-3ef7a31bc47f
                      relationships:
                        flow:
                          data:
                            id: 248c7776-bd9f-4075-8980-461b02ed3757
                            type: flow
                      meta:
                        owner: organization
                        timestamps:
                          created_at: '2017-06-26T12:55:33.560Z'
                          updated_at: '2017-12-19T12:31:24.570Z'
                    - id: 5f4be5bd-0c83-417a-b744-7d8c49636ab1
                      type: field
                      field_type: string
                      slug: background_image
                      name: Background Image
                      description: The background image for the category
                      required: false
                      default: null
                      enabled: true
                      validation_rules: []
                      order: null
                      omit_null: false
                      links:
                        self: https://useast.api.elasticpath.com/v2/flows/248c7776-bd9f-4075-8980-461b02ed3757/fields/5f4be5bd-0c83-417a-b744-7d8c49636ab1
                      relationships:
                        flow:
                          data:
                            id: 248c7776-bd9f-4075-8980-461b02ed3757
                            type: flow
                      meta:
                        owner: organization
                        timestamps:
                          created_at: '2018-03-29T10:33:24.056Z'
                          updated_at: '2018-03-29T10:33:24.056Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    FieldUpdateRequest:
      title: FieldUpdateRequest
      type: object
      properties:
        data:
          type: object
          properties:
            default:
              type: number
              description: A default value if none is supplied and the field/attribute is required.
              examples:
              - 1
            description:
              type: string
              description: A description for a field/attribute.
              examples:
              - Average rating as given by our users
            field_type:
              type: string
              description: "This field is immutable and cannot be updated. The type of field: \n- `string`\n- `integer`\n- `boolean`\n- `float`\n- `date`\n- `relationship`\n"
              examples:
              - integer
            id:
              $ref: '#/components/schemas/UUID'
            name:
              type: string
              description: The name of a field/attribute.
              examples:
              - Product Rating
            required:
              type: boolean
              description: '`true` if required on input, `false` if not. Always `false` if the `field_type` is `relationship`.

                '
              examples:
              - true
            slug:
              type: string
              description: A unique identifier of a field/attribute.
              examples:
              - product-rating
            enabled:
              type: boolean
              examples:
              - true
            type:
              type: string
              description: Represents the object being returned.
              examples:
              - field
    FieldValidationRules:
      type: object
      description: An array of validation rule objects. See [Field/attribute Validation Rules](#fieldattribute-validation-rules).
      properties:
        type:
          type: string
          description: The validation you use depends on the `field_type` of the field/attribute. Each validation rule is expressed as a validation rule object.
          example: enum
          enum:
          - enum
          - email
          - slug
          - between
          - one-to-many
          - one-to-one
        options:
          anyOf:
          - type: array
            description: An array of valid string values.
            items:
              type: string
          - type: object
            description: An object containing `from` and `to` integers.
            properties:
              from:
                type:
                - integer
                - string
                example: 1
              to:
                type:
                - integer
                - string
                example: 5
        to:
          type: string
          example: customer
    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'
    FieldRelationships:
      type: object
      description: Relationships are established between different flow/template entities. For example, a field/attribute is related to a flow/template, as the field/attribute is attached to the flow/template.
      required:
      - flow
      properties:
        flow:
          type: object
          required:
          - data
          properties:
            data:
              type: object
              required:
              - type
              - id
              properties:
                id:
                  $ref: '#/components/schemas/UUID'
                type:
                  type: string
                  description: Represents the type of object being returned.
                  example: flow
    ErrorResponse:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    FieldRequest:
      title: FieldRequest
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - required
          - type
          - field_type
          - slug
          - name
          - description
          properties:
            default:
              type: number
              description: Specifies a default value for a field/attribute if no value is provided and the field/attribute is required.
              examples:
              - 0
            description:
              type: string
              description: A description for a field/attribute.
              examples:
              - Average rating as given by our users
            enabled:
              type: boolean
              examples:
              - true
            field_type:
              type: string
              description: "This field is immutable and cannot be updated. You can have the following field types: \n - `string`\n - `integer`\n - `boolean`\n - `float`\n - `date`\n - `relationship`\n"
              examples:
              - integer
            name:
              type: string
              description: The name of a field/attribute.
              examples:
              - Product Rating
            order:
              type: number
              description: Denotes the order in which a field/attribute is returned relative to the rest of flow fields/template attributes.
              examples:
              - 1
            relationships:
              $ref: '#/components/schemas/FieldRelationships'
            required:
              type: boolean
              description: '`true` if required on input, `false` if not. Always `false` if the `field_type` `relationship`.

                '
              examples:
              - false
            slug:
              type: string
              description: A unique identifier of a field/attribute.
              examples:
              - product-rating
            type:
              type: string
              description: Represents the type of object being returned.
              examples:
              - field
            validation_rules:
              type: array
              items:
                $ref: '#/components/schemas/FieldValidationRules'
              description: An array of validation rule objects. See [**Field Validation Rules**](#fieldattribute-validation-rules).
              examples:
              - options:
                  from: 1
                  to: 5
                type: between
    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
    Field:
      title: Field
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          type: string
          description: Represents the type of object being returned.
          examples:
          - field
        field_type:
          type: string
          description: 'This field is immutable and cannot be updated. You can have the following field types:

            - `string`

            - `integer`

            - `boolean`

            - `float`

            - `date`

            - `relationship`

            '
          examples:
          - integer
        slug:
          type: string
          description: A short description for a field/attribute.
          examples:
          - product-rating
        name:
          type: string
          description: The name of a field/attribute.
          examples:
          - Product Rating
        description:
          type: string
          description: A short description of a field/attribute.
          examples:
          - Average rating as given by our users
        required:
          type: boolean
          description: '`true` if required on input, `false` if not. Always `false` if the `field_type` is a relationship.

            '
          examples:
          - true
        default:
          type:
          - number
          - string
          - 'null'
          description: A default value if none is supplied and a field/attribute is not required.
          examples:
          - 1
        enabled:
          type: boolean
          examples:
          - true
        order:
          type:
          - number
          - 'null'
          description: Denotes the order in which this field is returned relative to the rest of the flow/template fields/attributes.
          examples:
          - 1
        omit_null:
          type: boolean
          description: Hide this field/attribute from responses if the value is `null`.
          examples:
          - true
        validation_rules:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidationRules'
        meta:
          $ref: '#/components/schemas/Meta'
        links:
          $ref: '#/components/schemas/FieldLinks'
        relationships:
          $ref: '#/components/schemas/FieldRelationships'
    FieldLinks:
      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:


        | Property | Description |

        | --- | --- |

        | `current` | Always the current page |

        | `first` | Always the first page |

        | `last` | `null` if there is only one page. |

        | `prev` | `null` if you are on the first page. |

        | `next` | `null` if there is only one page. |

        '
      properties:
        self:
          type: string
          example: https://euwest.api.elasticpath.com/v2/flows/3cf3ad3f-b12c-4a08-a6ab-05e6aab0122c/fields/c1c788d1-f1c7-4b90-938f-f158f3353c66
    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
      

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-fields-api-openapi.yml