Spree Commerce Products API

openapi: 3.0.3
info:
  title: Admin Account / Address Products API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Validation failed\",\n    \"details\": { \"name\": [\"can't be blank\"] }\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Products
paths:
  /api/v3/admin/products/{product_id}/custom_fields:
    get:
      summary: List product custom fields
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: 'Returns the product''s custom field values.


        **Required scope:** `read_products` (for API-key authentication).'
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nconst { data: customFields } = await client.products.customFields.list('prod_UkLWZg9DAJ')"
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.
        schema:
          type: string
      responses:
        '200':
          description: custom fields found
          content:
            application/json:
              example:
                data:
                - id: cf_UkLWZg9DAJ
                  label: Title
                  type: Spree::Metafields::ShortText
                  field_type: short_text
                  key: custom.title
                  value: wool
                  created_at: '2026-05-24T17:37:32.172Z'
                  updated_at: '2026-05-24T17:37:32.172Z'
                  storefront_visible: true
                  custom_field_definition_id: cfdef_UkLWZg9DAJ
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous: null
                  next: null
    post:
      summary: Create a product custom field
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: 'Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.


        **Required scope:** `write_products` (for API-key authentication).'
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nconst customField = await client.products.customFields.create('prod_UkLWZg9DAJ', {\n  custom_field_definition_id: 'cfdef_AbC123XyZ',\n  value: 'wool',\n})"
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: custom field created
          content:
            application/json:
              example:
                id: cf_gbHJdmfrXB
                label: Description
                type: Spree::Metafields::LongText
                field_type: long_text
                key: custom.description
                value: A longer description
                created_at: '2026-05-24T17:37:32.769Z'
                updated_at: '2026-05-24T17:37:32.769Z'
                storefront_visible: true
                custom_field_definition_id: cfdef_gbHJdmfrXB
        '422':
          description: duplicate definition for the same product
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Metafield definition has already been taken
                  details:
                    metafield_definition_id:
                    - has already been taken
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - custom_field_definition_id
              - value
              properties:
                custom_field_definition_id:
                  type: string
                  description: Prefixed `cfdef_…` id
                value:
                  description: Value matching the definition's `field_type`
  /api/v3/admin/products/{product_id}/custom_fields/{id}:
    get:
      summary: Show a product custom field
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: '**Required scope:** `read_products` (for API-key authentication).'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.
        schema:
          type: string
      responses:
        '200':
          description: custom field found
          content:
            application/json:
              example:
                id: cf_UkLWZg9DAJ
                label: Title
                type: Spree::Metafields::ShortText
                field_type: short_text
                key: custom.title
                value: wool
                created_at: '2026-05-24T17:37:33.120Z'
                updated_at: '2026-05-24T17:37:33.120Z'
                storefront_visible: true
                custom_field_definition_id: cfdef_UkLWZg9DAJ
    patch:
      summary: Update a product custom field
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: 'Updates the custom field''s `value`. The linked definition cannot be changed — delete and recreate to switch.


        **Required scope:** `write_products` (for API-key authentication).'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: custom field updated
          content:
            application/json:
              example:
                id: cf_UkLWZg9DAJ
                label: Title
                type: Spree::Metafields::ShortText
                field_type: short_text
                key: custom.title
                value: cotton
                created_at: '2026-05-24T17:37:33.439Z'
                updated_at: '2026-05-24T17:37:33.726Z'
                storefront_visible: true
                custom_field_definition_id: cfdef_UkLWZg9DAJ
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - value
              properties:
                value:
                  description: New value
    delete:
      summary: Delete a product custom field
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: '**Required scope:** `write_products` (for API-key authentication).'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: custom field deleted
  /api/v2/platform/products:
    get:
      summary: Return a list of Products
      tags:
      - Products
      security:
      - bearer_auth: []
      description: Returns a list of Products
      operationId: products-list
      parameters:
      - name: page
        in: query
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        example: 50
        schema:
          type: integer
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: prices
        schema:
          type: string
      - name: filter[name_eq]
        in: query
        description: ''
        example: Green Toy Boat
        schema:
          type: string
      responses:
        '200':
          description: Records returned
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                    - id: '164'
                      type: product
                      attributes:
                        name: Product 1648238
                        description: 'Expedita a doloribus dolorum possimus architecto eligendi sunt quod. Officiis rerum nostrum incidunt delectus sint reiciendis doloribus ut. Atque voluptate nostrum voluptas unde repellendus.

                          Cum natus a id amet eos eligendi laborum. Minus itaque culpa aliquid repudiandae est odio reiciendis temporibus. Nesciunt cum voluptas veniam excepturi ducimus explicabo recusandae. Error quos voluptate reiciendis numquam dicta.'
                        available_on: '2021-11-08T19:34:52.496Z'
                        deleted_at: null
                        slug: product-1648238
                        meta_description: null
                        meta_keywords: null
                        created_at: '2022-11-08T19:34:52.514Z'
                        updated_at: '2022-11-08T19:34:52.520Z'
                        promotionable: true
                        meta_title: null
                        discontinue_on: null
                        public_metadata: {}
                        private_metadata: {}
                        status: active
                        make_active_at: '2021-11-08T19:34:52.496Z'
                        display_compare_at_price: null
                        display_price: $19.99
                        purchasable: true
                        in_stock: false
                        backorderable: true
                        available: true
                        currency: USD
                        price: '19.99'
                        compare_at_price: null
                      relationships:
                        tax_category:
                          data:
                            id: '108'
                            type: tax_category
                        primary_variant:
                          data:
                            id: '231'
                            type: variant
                        default_variant:
                          data:
                            id: '231'
                            type: variant
                        variants:
                          data: []
                        option_types:
                          data: []
                        product_properties:
                          data: []
                        taxons:
                          data: []
                        images:
                          data: []
                    - id: '165'
                      type: product
                      attributes:
                        name: Product 1653934
                        description: 'Blanditiis deleniti tempora provident culpa id doloremque. Quibusdam commodi minus magni asperiores nemo odio. Laborum mollitia alias quisquam exercitationem aliquam ex occaecati doloremque. Quos optio voluptatum suscipit soluta assumenda quaerat maxime fugit. In saepe quaerat exercitationem earum sequi.

                          Quidem nesciunt provident dicta explicabo autem nemo sunt. Iusto in provident officiis sed. Eveniet quam distinctio ipsam optio sint. Et autem ducimus vel voluptas facere.

                          Earum inventore ut eum eos numquam. Omnis nam provident atque temporibus. Natus illo voluptas enim ex optio eveniet ullam. Labore repudiandae laudantium non suscipit est quae. Odio provident a ad fuga accusamus distinctio vitae.

                          Doloremque quod similique ipsa quas perferendis rerum earum excepturi. Minus explicabo autem quod incidunt. Earum magnam voluptatem expedita eveniet reiciendis dolores atque et.

                          Inventore odio voluptate dicta dolore natus aut occaecati molestiae. Aut eum consequatur soluta voluptatum animi delectus accusantium asperiores. Facere exercitationem consequuntur adipisci nulla similique perferendis ullam. Illo ad aliquid maiores non ea.'
                        available_on: '2021-11-08T19:34:52.538Z'
                        deleted_at: null
                        slug: product-1653934
                        meta_description: null
                        meta_keywords: null
                        created_at: '2022-11-08T19:34:52.549Z'
                        updated_at: '2022-11-08T19:34:52.555Z'
                        promotionable: true
                        meta_title: null
                        discontinue_on: null
                        public_metadata: {}
                        private_metadata: {}
                        status: active
                        make_active_at: '2021-11-08T19:34:52.538Z'
                        display_compare_at_price: null
                        display_price: $19.99
                        purchasable: true
                        in_stock: false
                        backorderable: true
                        available: true
                        currency: USD
                        price: '19.99'
                        compare_at_price: null
                      relationships:
                        tax_category:
                          data:
                            id: '108'
                            type: tax_category
                        primary_variant:
                          data:
                            id: '232'
                            type: variant
                        default_variant:
                          data:
                            id: '232'
                            type: variant
                        variants:
                          data: []
                        option_types:
                          data: []
                        product_properties:
                          data: []
                        taxons:
                          data: []
                        images:
                          data: []
                    meta:
                      count: 2
                      total_count: 2
                      total_pages: 1
                    links:
                      self: http://www.example.com/api/v2/platform/products?page=1&per_page=&include=&filter[name_eq]=
                      next: http://www.example.com/api/v2/platform/products?filter%5Bname_eq%5D=&include=&page=1&per_page=
                      prev: http://www.example.com/api/v2/platform/products?filter%5Bname_eq%5D=&include=&page=1&per_page=
                      last: http://www.example.com/api/v2/platform/products?filter%5Bname_eq%5D=&include=&page=1&per_page=
                      first: http://www.example.com/api/v2/platform/products?filter%5Bname_eq%5D=&include=&page=1&per_page=
              schema:
                $ref: '#/components/schemas/resources_list'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
    post:
      summary: Create a Product
      tags:
      - Products
      security:
      - bearer_auth: []
      description: Creates a Product
      operationId: create-product
      parameters:
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: prices
        schema:
          type: string
      responses:
        '201':
          description: Record created
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '168'
                      type: product
                      attributes:
                        name: Spinning Top
                        description: null
                        available_on: null
                        deleted_at: null
                        slug: spinning-top
                        meta_description: null
                        meta_keywords: null
                        created_at: '2022-11-08T19:34:53.239Z'
                        updated_at: '2022-11-08T19:34:53.243Z'
                        promotionable: true
                        meta_title: null
                        discontinue_on: null
                        public_metadata: {}
                        private_metadata: {}
                        status: draft
                        make_active_at: null
                        display_compare_at_price: null
                        display_price: $87.43
                        purchasable: false
                        in_stock: false
                        backorderable: false
                        available: false
                        currency: USD
                        price: '87.43'
                        compare_at_price: null
                      relationships:
                        tax_category:
                          data: null
                        primary_variant:
                          data:
                            id: '235'
                            type: variant
                        default_variant:
                          data:
                            id: '235'
                            type: variant
                        variants:
                          data: []
                        option_types:
                          data: []
                        product_properties:
                          data: []
                        taxons:
                          data: []
                        images:
                          data: []
              schema:
                $ref: '#/components/schemas/resource'
        '422':
          description: Invalid request
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: Name can't be blank, Shipping Category can't be blank, and Price can't be blank
                    errors:
                      name:
                      - can't be blank
                      shipping_category:
                      - can't be blank
                      price:
                      - can't be blank
              schema:
                $ref: '#/components/schemas/validation_errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_product_params'
  /api/v2/platform/products/{id}:
    get:
      summary: Return a Product
      tags:
      - Products
      security:
      - bearer_auth: []
      description: Returns a Product
      operationId: show-product
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: prices
        schema:
          type: string
      responses:
        '200':
          description: Record found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '169'
                      type: product
                      attributes:
                        name: Product 1682525
                        description: 'Enim quibusdam et quis in iste. Eius labore corporis tempora suscipit molestiae sunt. Omnis vero numquam nostrum totam illum consectetur similique corporis.

                          Iusto neque beatae consequatur consequuntur soluta pariatur at. Magnam numquam nisi voluptatem ipsa blanditiis ullam iste mollitia. Incidunt totam earum perferendis eveniet iusto ea. Sapiente est quam corporis veniam eveniet itaque.

                          Repudiandae autem cumque hic nisi perferendis cum quod nostrum. Voluptatem ipsam esse provident itaque similique quia. Nobis quod blanditiis atque cupiditate eaque perspiciatis ullam in. Sequi aspernatur eaque reiciendis error illo dolorum pariatur.

                          Sit recusandae reiciendis magni ipsam repudiandae est dolor quae. Veritatis possimus eveniet iusto dignissimos quasi consequatur temporibus. Magni asperiores officiis occaecati provident velit quos a voluptate.'
                        available_on: '2021-11-08T19:34:53.563Z'
                        deleted_at: null
                        slug: product-1682525
                        meta_description: null
                        meta_keywords: null
                        created_at: '2022-11-08T19:34:53.582Z'
                        updated_at: '2022-11-08T19:34:53.588Z'
                        promotionable: true
                        meta_title: null
                        discontinue_on: null
                        public_metadata: {}
                        private_metadata: {}
                        status: active
                        make_active_at: '2021-11-08T19:34:53.563Z'
                        display_compare_at_price: null
                        display_price: $19.99
                        purchasable: true
                        in_stock: false
                        backorderable: true
                        available: true
                        currency: USD
                        price: '19.99'
                        compare_at_price: null
                      relationships:
                        tax_category:
                          data:
                            id: '110'
                            type: tax_category
                        primary_variant:
                          data:
                            id: '236'
                            type: variant
                        default_variant:
                          data:
                            id: '236'
                            type: variant
                        variants:
                          data: []
                        option_types:
                          data: []
                        product_properties:
                          data: []
                        taxons:
                          data: []
                        images:
                          data: []
              schema:
                $ref: '#/components/schemas/resource'
        '404':
          description: Record not found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The resource you were looking for could not be found.
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
    patch:
      summary: Update a Product
      tags:
      - Products
      security:
      - bearer_auth: []
      description: Updates a Product
      operationId: update-product
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: prices
        schema:
          type: string
      responses:
        '200':
          description: Record updated
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '171'
                      type: product
                      attributes:
                        name: Twirling Bottom
                        description: 'Ut quod iusto optio quos labore. Blanditiis in sunt sequi dolores eveniet reprehenderit maxime. Iusto consequuntur itaque nostrum placeat.

                          Laboriosam labore vero voluptatibus suscipit consectetur possimus qui. Ullam commodi corporis cumque voluptatem neque non explicabo. Quaerat atque error nesciunt recusandae rem unde qui quas. Labore perspiciatis consectetur quisquam voluptatibus similique officiis ipsam enim. Labore neque reprehenderit et tempore.

                          Ea minus nostrum placeat quibusdam laudantium. Illo voluptates in suscipit consequatur harum. Omnis tempora facilis distinctio quos repudiandae ex sapiente. Amet optio temporibus voluptas doloribus.

                          Odio at porro commodi repudiandae quia quas. Ut sequi atque accusamus voluptatum consequatur delectus explicabo. Nobis laboriosam facere molestias consectetur saepe totam eos ea. Possimus atque adipisci sequi dolorum excepturi quo. Ad esse dolorum accusantium fugiat quaerat.

                          Voluptas libero magnam earum reprehenderit ullam at veritatis. Magni culpa id quidem hic ad. Quidem ipsum est vero ut eaque veniam. Corrupti sint ratione maxime aspernatur itaque quo nostrum. Qui architecto ducimus quisquam iste saepe ullam.'
                        available_on: '2021-11-08T19:34:54.192Z'
                        deleted_at: null
                        slug: product-1706992
                        meta_description: null
                        meta_keywords: null
                        created_at: '2022-11-08T19:34:54.210Z'
                        updated_at: '2022-11-08T19:34:54.468Z'
                        promotionable: true
                        meta_title: null
                        discontinue_on: null
                        public_metadata: {}
                        private_metadata: {}
                        status: active
                        make_active_at: '2021-11-08T19:34:54.192Z'
                        display_compare_at_price: null
                        display_price: $33.21
                        purchasable: true
                        in_stock: false
                        backorderable: true
                        available: true
                        currency: USD
                        price: '33.21'
                        compare_at_price: null
                      relationships:
                        tax_category:
                          data:
                            id: '112'
                            type: tax_category
                        primary_variant:
                          data:
                            id: '238'
                            type: variant
                        default_variant:
                          data:
                            id: '238'
                            type: variant
                        variants:
                          data: []
                        option_types:
                          data: []
                        product_properties:
                          data: []
                        taxons:
                          data: []
                        images:
                          data: []
              schema:
                $ref: '#/components/schemas/resource'
        '422':
          description: Invalid request
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: Name can't be blank
                    errors:
                      name:
                      - can't be blank
              schema:
                $ref: '#/components/schemas/validation_errors'
        '404':
          description: Record not found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The resource you were looking for could not be found.
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_product_params'
    delete:
      summary: Delete a Product
      tags:
      - Products
      security:
      - bearer_auth: []
      description: Deletes a Product
      operationId: delete-product
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Record deleted
        '404':
          description: Record not found
          content:
            application/vnd.api+json:
              examples:
    

# --- truncated at 32 KB (148 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree-commerce/refs/heads/main/openapi/spree-commerce-products-api-openapi.yml