Ometria Products API

openapi: 3.2.0
info:
  version: 1.1.0
  title: Ometria data Products API
  description: 'Welcome to the Ometria API reference.


    The Ometria API is organized around the REST methodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors. All requests are authenticated using an API key which can be obtained from your account settings.


    ### HTTPS


    All requests to the Ometria API MUST be carried out via HTTPS. API servers do not listen on unsecured HTTP ports to avoid the possibility of insecure information exchange.


    ### Message encoding


    The V2 Ometria API uses JSON encoding for all data exchanges and assumes UTF-8 character encoding throughout.


    ### Rate limits


    The Ometria API has a default rate limit of 4 requests per second per Ometria account. The /push/ endpoint allows 8 requests per second per Ometria account. If you expect to exceed this limit, please contact us.


    In the case of your application being rate limited, the HTTP code 429 (too many requests) will be returned. In this case your application should reduce the number of requests it is trying to send.'
  contact:
    name: Ometria
    email: support@ometria.com
    url: https://ometria.com
servers:
- url: https://api.ometria.com/v2
security:
- apikey: []
tags:
- name: Products
paths:
  /products:
    get:
      tags:
      - Products
      summary: List Products
      description: Return a list of products with optional filters
      parameters:
      - name: limit
        in: query
        description: The number of items to return. Max 250.
        required: false
        schema:
          type: string
          default: '10'
      - name: offset
        in: query
        description: The index of first the record to return.
        required: false
        schema:
          type: string
          default: '0'
      - name: active
        in: query
        description: Should we return only active or inactive products? `True` to return only active. 'False' to return only inactive. If this parameter is not defined, both active and inactive products are returned.
        required: false
        allowEmptyValue: true
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: includeVariants
        in: query
        description: Product variants (or child products) for shippable SKUs.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: List of Product objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
        '403':
          description: API key is not authorised to access this resource
      operationId: getProducts
      x-operation-id-source: derived
  /products/{product_id}:
    get:
      tags:
      - Products
      summary: Get Product
      description: Return a single Product item
      parameters:
      - name: product_id
        in: path
        description: The ID of the product to return.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Product object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '403':
          description: API key is not authorised to access this resource
        '404':
          description: Product with specified ID was not found
      operationId: getProductsByProductId
      x-operation-id-source: derived
components:
  schemas:
    ProductListing:
      type: object
      description: Describes an individual store listing for a product.
      required:
      - title
      - price
      - store
      - currency
      properties:
        title:
          type: string
          description: 'The title of the product, max length: 140.

            If you exceed the character limit the field will pass validation but appear truncated in Ometria.'
        price:
          type: number
          description: The price of the product.
          format: float
        store:
          type: string
          description: 'Required. Identifier representing the store the product belongs to. This will match the code passed in an order.

            Max length: 32, must be lower case. Example: `_store_1234`.'
        currency:
          type: string
          description: 'The currency for this product listing.

            Must follow ISO 4217 format, max length: 3, upper case.

            This field is required if you are using the listings array.

            If left empty this field is set to ''null''.'
          minLength: 3
          maxLength: 3
        is_active:
          type: boolean
          description: 'Is this product listing considered active on the website? I.e. Is it visible and available to purchase?

            Use "is_in_stock" to indicate whether a product is in stock or not.'
        special_price:
          type: number
          description: A <a href="https://ometria-api-reference.readme.io/docs/product-endpoint#special-price" target="_blank">special</a> (discounted) price used in connection with special_price_dt_from and special_price_dt_to on the parent product object.
          format: float
        url:
          type: string
          description: 'The URL to this product listing on your site, max length: 1024.'
        image_url:
          type: string
          description: 'The URL to the product listing''s image on your site, max length: 1024.'
      example:
        title: Produit d'essai
        is_active: true
        currency: EUR
        price: 59.99
        url: http://www.example.com/fr/product.html
        image_url: http://www.example.com/fr/product.jpg
        store: example.com/fr
    ProductAttribute:
      type: object
      description: Describes an attribute attached to a Product.
      required:
      - type
      - id
      - label
      properties:
        type:
          type: string
          description: 'The type of the attribute, max length: 128.

            This field is required if you are using the attributes array.'
        id:
          type: string
          description: 'The ID of the attribute, max length: 128.'
        label:
          type: string
          description: 'The label of the attribute, max length: 128'
      example:
        type: category
        id: category:womens
        label: Womens
    Product:
      title: Product
      type: object
      description: Describes a Product record.
      required:
      - '@type'
      - id
      - title
      - price
      properties:
        '@type':
          type: string
          description: The value must be "product". This shows that this record represents a product object.
        id:
          type: string
          description: 'The ID of the product. Max length: 255.'
        title:
          type: string
          description: 'The title of this product as displayed to customers, max length: 140.

            If you exceed the character limit, this field will pass validation but appear truncated in the Ometria interface.'
        is_variant:
          type: boolean
          description: Whether or not this product record represents a <a href="https://ometria-api-reference.readme.io/docs/products-product-listings-and-product-variants" target="_blank">variant product</a>.
        parent_id:
          type: string
          description: 'The ID of the parent product, if this product is a variant. Max length: 255.'
        price:
          type: number
          description: The default display price (account default currency / store).
          format: float
        sku:
          type: string
          description: 'The SKU of the product, max length: 255.

            If left empty this field is set to `null`.'
        special_price_dt_from:
          type: string
          description: Optional. The datetime that the <a href="https://ometria-api-reference.readme.io/docs/product-endpoint#special-price" target="_blank">special price</a> begins. Format YYYY-MM-DD HH:II:SS.
          format: date-time
        special_price_dt_to:
          type: string
          description: Optional. The datetime that the <a href="https://ometria-api-reference.readme.io/docs/product-endpoint#special-price" target="_blank">special price</a> ends. Format YYYY-MM-DD HH:II:SS.
          format: date-time
        special_price:
          type: number
          description: Optional. A <a href="https://ometria-api-reference.readme.io/docs/product-endpoint#special-price" target="_blank">special</a> (discounted) price used in conjunction with special_price_dt_from and special_price_dt_to.
          format: float
        is_active:
          description: Is this product considered active on the website?. E.g. is it visible and (in principle) buyable? Please use "is_in_stock" to indicate whether a product is in stock or not.
          type: boolean
        is_in_stock:
          type: boolean
          description: Is this product in stock?
        url:
          type: string
          description: 'The URL to the product''s page on your site, max length: 1024.'
        image_url:
          type: string
          description: 'The URL to the product''s image on your site, max length: 1024.'
        attributes:
          description: Array of ProductAttribute objects.
          type: array
          items:
            $ref: '#/components/schemas/ProductAttribute'
        listings:
          description: Array of ProductListing objects used to work out which stores this product is available in, and any store specific details.
          type: array
          items:
            $ref: '#/components/schemas/ProductListing'
        properties:
          type: object
          description: Custom key / value pairs accessible in emails using this product object
      example:
        '@type': product
        id: '12345'
        sku: FHSG-2738-FHI
        title: Test Product
        price: 50
        special_price_dt_to: '2015-01-02T09:00:00+00'
        special_price_dt_from: '2015-03-02T09:00:00+00'
        special_price: 45
        is_active: true
        url: http://www.example.com/product.html
        image_url: http://www.example.com/product.jpg
        properties:
          custom_key: custom value
        attributes:
        - type: category
          id: category:womens
          label: Womens
        - type: style
          id: style:casual
          label: Casual
        listings:
        - title: Produit d'essai
          is_active: true
          currency: EUR
          price: 50
          url: http://www.example.com/fr/product.html
          image_url: http://www.example.com/fr/product.jpg
          store: example.com/fr
        - title: Das Product
          is_active: false
          currency: EUR
          price: 50
          url: http://www.example.com/de/product.html
          image_url: http://www.example.com/de/product.jpg
          store: example.com/de
  securitySchemes:
    apikey:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: Ometria API key which can be obtained from your Ometria account administrator
    apiKeyReadTranslations:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `read:translations`.'
    apiKeyWriteTranslations:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `write:translations`.'
x-explorer-enabled: false
x-readme:
  proxy-enabled: true
  samples-enabled: true