openapi: 3.0.3
info:
  title: Admin Account / Address Variants 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: Variants
paths:
  /api/v2/platform/variants:
    get:
      summary: Return a list of Variants
      tags:
      - Variants
      security:
      - bearer_auth: []
      description: Returns a list of Variants
      operationId: variants-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: product,tax_category,images,digitals
        schema:
          type: string
      - name: filter[product_id_eq]
        in: query
        description: ''
        example: '1'
        schema:
          type: string
      - name: filter[sku_i_cont]
        in: query
        description: ''
        example: SKU123
        schema:
          type: string
      responses:
        '200':
          description: Records returned
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                    - id: '284'
                      type: variant
                      attributes:
                        sku: SKU-283
                        weight: '0.0'
                        height: null
                        depth: null
                        deleted_at: null
                        is_master: true
                        cost_price: '17.0'
                        position: 1
                        cost_currency: USD
                        track_inventory: true
                        updated_at: '2022-11-08T19:35:56.573Z'
                        discontinue_on: null
                        created_at: '2022-11-08T19:35:56.573Z'
                        public_metadata: {}
                        private_metadata: {}
                        barcode: null
                        display_price: $19.99
                        display_compare_at_price: null
                        name: Product 213286
                        options_text: ''
                        total_on_hand: 0
                        purchasable: true
                        in_stock: false
                        backorderable: true
                        available: true
                        currency: USD
                        price: '19.99'
                        compare_at_price: null
                      relationships:
                        product:
                          data:
                            id: '214'
                            type: product
                        tax_category:
                          data: null
                        digitals:
                          data: []
                        images:
                          data: []
                        option_values:
                          data: []
                        stock_items:
                          data:
                          - id: '300'
                            type: stock_item
                        stock_locations:
                          data:
                          - id: '187'
                            type: stock_location
                    - id: '285'
                      type: variant
                      attributes:
                        sku: SKU-284
                        weight: '23.12'
                        height: '92.8'
                        depth: '47.37'
                        deleted_at: null
                        is_master: false
                        cost_price: '17.0'
                        position: 2
                        cost_currency: USD
                        track_inventory: true
                        updated_at: '2022-11-08T19:35:56.608Z'
                        discontinue_on: null
                        created_at: '2022-11-08T19:35:56.605Z'
                        public_metadata: {}
                        private_metadata: {}
                        barcode: null
                        display_price: $19.99
                        display_compare_at_price: null
                        name: Product 213286
                        options_text: 'Size: S'
                        total_on_hand: 0
                        purchasable: true
                        in_stock: false
                        backorderable: true
                        available: true
                        currency: USD
                        price: '19.99'
                        compare_at_price: null
                      relationships:
                        product:
                          data:
                            id: '214'
                            type: product
                        tax_category:
                          data: null
                        digitals:
                          data: []
                        images:
                          data: []
                        option_values:
                          data:
                          - id: '83'
                            type: option_value
                        stock_items:
                          data:
                          - id: '301'
                            type: stock_item
                        stock_locations:
                          data:
                          - id: '187'
                            type: stock_location
                    - id: '286'
                      type: variant
                      attributes:
                        sku: SKU-285
                        weight: '90.94'
                        height: '108.64'
                        depth: '191.7'
                        deleted_at: null
                        is_master: false
                        cost_price: '17.0'
                        position: 3
                        cost_currency: USD
                        track_inventory: true
                        updated_at: '2022-11-08T19:35:56.633Z'
                        discontinue_on: null
                        created_at: '2022-11-08T19:35:56.629Z'
                        public_metadata: {}
                        private_metadata: {}
                        barcode: null
                        display_price: $19.99
                        display_compare_at_price: null
                        name: Product 213286
                        options_text: 'Size: S'
                        total_on_hand: 0
                        purchasable: true
                        in_stock: false
                        backorderable: true
                        available: true
                        currency: USD
                        price: '19.99'
                        compare_at_price: null
                      relationships:
                        product:
                          data:
                            id: '214'
                            type: product
                        tax_category:
                          data: null
                        digitals:
                          data: []
                        images:
                          data: []
                        option_values:
                          data:
                          - id: '84'
                            type: option_value
                        stock_items:
                          data:
                          - id: '302'
                            type: stock_item
                        stock_locations:
                          data:
                          - id: '187'
                            type: stock_location
                    meta:
                      count: 3
                      total_count: 3
                      total_pages: 1
                    links:
                      self: http://www.example.com/api/v2/platform/variants?page=1&per_page=&include=&filter[product_id_eq]=&filter[sku_i_cont]=
                      next: http://www.example.com/api/v2/platform/variants?filter%5Bproduct_id_eq%5D=&filter%5Bsku_i_cont%5D=&include=&page=1&per_page=
                      prev: http://www.example.com/api/v2/platform/variants?filter%5Bproduct_id_eq%5D=&filter%5Bsku_i_cont%5D=&include=&page=1&per_page=
                      last: http://www.example.com/api/v2/platform/variants?filter%5Bproduct_id_eq%5D=&filter%5Bsku_i_cont%5D=&include=&page=1&per_page=
                      first: http://www.example.com/api/v2/platform/variants?filter%5Bproduct_id_eq%5D=&filter%5Bsku_i_cont%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'
  /api/v2/platform/variants/{id}:
    get:
      summary: Return a Variant
      tags:
      - Variants
      security:
      - bearer_auth: []
      description: Returns a Variant
      operationId: show-variant
      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: product,tax_category,images,digitals
        schema:
          type: string
      responses:
        '200':
          description: Record found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '291'
                      type: variant
                      attributes:
                        sku: SKU-290
                        weight: '185.0'
                        height: '33.55'
                        depth: '3.78'
                        deleted_at: null
                        is_master: false
                        cost_price: '17.0'
                        position: 2
                        cost_currency: USD
                        track_inventory: true
                        updated_at: '2022-11-08T19:35:57.221Z'
                        discontinue_on: null
                        created_at: '2022-11-08T19:35:57.218Z'
                        public_metadata: {}
                        private_metadata: {}
                        barcode: null
                        display_price: $19.99
                        display_compare_at_price: null
                        name: Product 2153349
                        options_text: 'Size: S'
                        total_on_hand: 0
                        purchasable: true
                        in_stock: false
                        backorderable: true
                        available: true
                        currency: USD
                        price: '19.99'
                        compare_at_price: null
                      relationships:
                        product:
                          data:
                            id: '216'
                            type: product
                        tax_category:
                          data: null
                        digitals:
                          data: []
                        images:
                          data: []
                        option_values:
                          data:
                          - id: '87'
                            type: option_value
                        stock_items:
                          data:
                          - id: '307'
                            type: stock_item
                        stock_locations:
                          data:
                          - id: '189'
                            type: stock_location
              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'
    delete:
      summary: Delete a Variant
      tags:
      - Variants
      security:
      - bearer_auth: []
      description: Deletes a Variant
      operationId: delete-variant
      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:
                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'
  /api/v2/storefront/products/{product_slug}/variants:
    get:
      description: 'Returns a list of product variants. You can use product permalink:


        ```

        GET /api/v2/storefront/products/knitted-high-neck-sweater/variants

        ```


        Or Product ID:


        ```

        GET /api/v2/storefront/products/21/variants

        ```


        **Note** API will attempt a permalink lookup before an ID lookup.'
      tags:
      - Variants
      operationId: variants-list
      parameters:
      - $ref: '#/components/parameters/ProductSlug'
      - in: query
        name: filter[options][color]
        schema:
          type: string
        example: red
        description: Find Variants that have the specified option (eg. color, size) and value (eg. red, XS)
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/VariantIncludeParam'
      - $ref: '#/components/parameters/SparseFieldsVariant'
      responses:
        '200':
          $ref: '#/components/responses/VariantList'
      summary: List all Product Variants
components:
  schemas:
    ListMeta:
      type: object
      x-internal: false
      title: Pagination Meta
      properties:
        count:
          type: number
          example: 7
          description: Number of items on the current listing
        total_count:
          type: number
          example: 145
          description: Number of all items matching the criteria
        total_pages:
          type: number
          example: 10
          description: Number of all pages containing items matching the criteria
    resource_properties:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        attributes:
          type: object
        relationships:
          type: object
      required:
      - id
      - type
      - attributes
      x-internal: false
    ImageStyle:
      x-internal: false
      title: Image Style
      type: object
      properties:
        url:
          type: string
          example: http://localhost:3000/rails/active_storage/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJbWQyWVhKcFlXNTBjeTltWm1sMmRURlNORFpZWjJaSFpYUkdZMjk2WWsxM1RHWXZNVGs1T1RCak5XVmlNamN4TlRnd1pqVTBabUpqTWpCbFkyVXhZMlZpTTJFd05ERTJZemMzT0dKaE5tSTFNREkyT0dKaFpqa3paV1JtWTJWaE16aGxaQVk2QmtWVSIsImV4cCI6IjIwMTgtMDYtMjRUMTM6NTk6NTguOTY5WiIsInB1ciI6ImJsb2Jfa2V5In19--5e9ff358dc747f73754e332678c5762114ac6f3f/ror_jr_spaghetti.jpeg?content_type=image%2Fjpeg&disposition=inline%3B+filename%3D%22ror_jr_spaghetti.jpeg%22%3B+filename%2A%3DUTF-8%27%27ror_jr_spaghetti.jpeg
          description: Absolute URL of the uploaded image in selected style (width/height)
        width:
          type: integer
          example: 1920
          description: Actual width of image
        height:
          type: integer
          example: 1080
          description: Actual height of image
    Product:
      type: object
      title: Product
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: product
        attributes:
          type: object
          properties:
            name:
              type: string
              example: Example product
            description:
              type: string
              example: Example description
              nullable: true
            available_on:
              type: string
              example: '2012-10-17T03:43:57Z'
              nullable: true
            slug:
              type: string
              example: example-product
            price:
              type: string
              example: '15.99'
              nullable: true
            currency:
              type: string
              example: USD
            display_price:
              type: string
              example: $15.99
              nullable: true
            purchasable:
              type: boolean
              description: Indicates if any of Variants are in stock or backorderable
            in_stock:
              type: boolean
              description: Indicates if any of Variants are in stock
            backorderable:
              type: boolean
              description: Indicates if any of Variants are backeorderable
            meta_description:
              type: string
              example: Example product
              nullable: true
            meta_keywords:
              type: string
              example: example, product
              nullable: true
            updated_at:
              $ref: '#/components/schemas/Timestamp'
            sku:
              type: string
              example: 9238-WS
            available:
              type: boolean
            compare_at_price:
              type: string
              example: '49.99'
              nullable: true
            display_compare_at_price:
              type: string
              example: $49.99
              nullable: true
            localized_slugs:
              type: object
              description: Provides product's slugs in other locales
            tags:
              type: array
              items:
                type: string
              description: List of tags associated with the product
            labels:
              type: array
              items:
                type: string
              description: List of labels associated with the product
        relationships:
          type: object
          properties:
            variants:
              type: object
              description: List of Product Variants, excluding Master Variant
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            option_types:
              type: object
              description: List of Product Option Types
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            product_properties:
              type: object
              description: List of Product Properties
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            taxons:
              type: object
              description: List of Taxons associated with this Product
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            images:
              type: object
              description: List of Images associated with this Product
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            default_variant:
              type: object
              description: The default Variant for this product
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            primary_variant:
              type: object
              description: The Primary Variant for this product
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
    resource:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/resource_properties'
      required:
      - data
      x-internal: false
    ListLinks:
      x-internal: false
      type: object
      title: Pagination Links
      properties:
        self:
          type: string
          description: URL to the current page of the listing
        next:
          type: string
          description: URL to the next page of the listing
        prev:
          type: string
          description: URL to the previous page of the listing
        last:
          type: string
          description: URL to the last page of the listing
        first:
          type: string
          description: URL to the first page of the listing
    resources_list:
      type: object
      properties:
        data:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/resource_properties'
        meta:
          type: object
          properties:
            count:
              type: integer
            total_count:
              type: integer
            total_pages:
              type: integer
          required:
          - count
          - total_count
          - total_pages
        links:
          type: object
          properties:
            self:
              type: string
            next:
              type: string
            prev:
              type: string
            last:
              type: string
            first:
              type: string
          required:
          - self
          - next
          - prev
          - last
          - first
      required:
      - data
      - meta
      - links
      x-internal: false
    Image:
      type: object
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: image
        attributes:
          type: object
          properties:
            position:
              type: integer
              description: Sort order of images set in the Admin Panel
              example: 0
              minimum: 0
            styles:
              type: array
              description: An array of pre-scaled image styles
              items:
                $ref: '#/components/schemas/ImageStyle'
      required:
      - id
      - type
      - attributes
      title: Image
      x-internal: false
    VariantIncludes:
      x-internal: true
      title: Product Includes
      anyOf:
      - $ref: '#/components/schemas/Product'
      - $ref: '#/components/schemas/Image'
      - $ref: '#/components/schemas/OptionValue'
    Relation:
      type: object
      nullable: true
      properties:
        id:
          type: string
        type:
          type: string
      required:
      - id
      - type
      x-internal: false
      description: ''
    error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
      x-internal: false
    OptionValue:
      title: Option Value
      type: object
      x-internal: true
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: option_value
        attributes:
          type: object
          properties:
            name:
              type: string
              example: color
            presentation:
              type: string
              example: Color
            position:
              type: integer
              example: 1
        relationships:
          type: object
          properties:
            option_type:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            filter_value:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
    Timestamp:
      type: string
      format: date-time
      example: '2020-02-16T07:14:54.617Z'
      x-internal: false
      title: Time Stamp
      x-examples:
        example-1: '2020-02-16T07:14:54.617Z'
    Variant:
      title: Variant
      description: 'Variant records track the individual variants of a Product. Variants are of two types: master variants and normal variants.'
      x-examples: {}
      type: object
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: variant
        attributes:
          type: object
          properties:
            sku:
              type: string
              example: SKU-1001
            price:
              type: string
              example: '15.99'
            currency:
              type: string
              example: USD
            display_price:
              type: string
              example: $15.99
            weight:
              type: string
              example: '10'
              nullable: true
            height:
              type: string
              example: '10'
              nullable: true
            width:
              type: string
              example: '10'
              nullable: true
            depth:
              type: string
              example: '10'
              nullable: true
            is_master:
              type: boolean
              description: Indicates if Variant is the master Variant
            options_text:
              type: string
              example: 'Size: small, Color: red'
            options:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
                  presentation:
                    type: string
            purchasable:
              type: boolean
              description: Indicates if Variant is in stock or backorderable
            in_stock:
              type: boolean
              description: Indicates if Variant is in stock
            backorderable:
              type: boolean
        relationships:
          type: object
          properties:
            product:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            images:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            option_values:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
  parameters:
    ProductSlug:
      name: product_slug
      in: path
      required: true
      description: Product Slug
      schema:
        type: string
      example: knitted-high-neck-sweater
    SparseFieldsVariant:
      name: fields[variant]
      in: query
      description: Specify the fields you would like returned in the response body. [More information](https://jsonapi.org/format/#fetching-sparse-fieldsets).
      schema:
        type: string
      example: price,currency,options,options_text
    PageParam:
      name: page
      in: query
      description: Number of requested page when paginating collection
      schema:
        type: integer
      example: 1
    PerPageParam:
      name: per_page
      in: query
      description: Number of requested records per page when paginating collection
      schema:
        type: integer
      example: 25
    VariantIncludeParam:
      name: include
      in: query
      schema:
        type: string
      description: 'Specify what related resources (relationships) you would like to receive in the response body. Eg.


        ```

        product,option_values,images,filter_values

        ```


        [More information](https://jsonapi.org/format/#fetching-includes)'
      example: product,option_values,images,filter_values
  responses:
    VariantList:
      description: 200 Success - Returns an array of `variant` objects.
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/Variant'
              included:
                type: array
                items:
                  $ref: '#/components/schemas/VariantIncludes'
              meta:
                $ref: '#/components/schemas/ListMeta'
              links:
                $ref: '#/components/schemas/ListLinks'
            required:
            - data
            - meta
            - links
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Secret API key for admin access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for admin user authentication
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
- name: Product Catalog
  tags:
  - Product Catalog
- name: Orders
  tags:
  - Orders
- name: Customers
  tags:
  - Customers
- name: Configuration
  tags:
  - Configuration