Instock Articles API

openapi: 3.2.0
info:
  contact:
    name: Instock
    email: info@instock.com
    url: https://instock.com
  license:
    name: Instock
    url: https://instock.com
  title: Instock API reference Articles API
  version: 0.1.0
  description: '# Overview

    This reference is a comprehensive guide to understanding of Instock API and is aimed to

    help developers to integrate their Host system with Instock Cloud (Incloud).'
servers:
- url: https://api.instock.com/v1
security:
- bearerAuth: []
tags:
- name: Articles
  description: Instock is using the term `article` to describe unique product or SKU managed by Instock ASRS.
paths:
  /articles:
    post:
      tags:
      - Articles
      summary: Upload article(s)
      description: 'Uploads single or multiple articles to your Instock organization account.


        **Note**:

        * if a particular article is not uploaded to your organization, warehouse operators won''t be able to

        receive it into Instock ASRS (decant).

        * if bulk article upload contains at least one article that cannot be validated, Incloud will yield `400`

        and entire request will fail.

        * bulk article upload has a limit of maximum 1000 articles per request.'
      operationId: uploadArticles
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X POST 'https://api.instock.com/v1/articles' \\\n-H 'Authorization: Bearer {ACCESS_TOKEN}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"articles\": [\n    {\n      \"article_id\": \"016000124790\",\n      \"name\": \"Honey Nut Cheerios (10.8oz)\",\n      \"is_serial_numbered\": false,\n      \"dimensions\": {\n        \"x\": \"1.9\",\n        \"y\": \"7.7\",\n        \"z\": \"11.3\",\n        \"uom\": \"in\"\n      },\n      \"attributes\": {\n        \"product_category_name\": \"Cereals and bars\",\n        \"temp_zone\": \"ambient\"\n      }\n    },\n    {\n      \"article_id\": \"HOOD_M_SIZE_2A1T\",\n      \"name\": \"Relaxed fit pullover hooded sewatshirt\",\n      \"is_serial_numbered\": false,\n      \"dimensions\": {\n        \"x\": \"12\",\n        \"y\": \"2\",\n        \"z\": \"14\",\n        \"uom\": \"in\"\n      },\n      \"attributes\": {\n        \"product_category_name\": \"Apparel\",\n        \"product_photo\": \"https://via.placeholder.com/image.png\",\n        \"product_size\": \"M\",\n      }\n    }\n  ]\n}'\n"
      parameters:
      - $ref: '#/components/parameters/instockCorrelationID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createArticles'
            examples:
              Create single article:
                $ref: '#/components/examples/SingleArticle'
              Create multiple articles:
                $ref: '#/components/examples/MultipleArticles'
      responses:
        '200':
          description: Successful operation.
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                type: string
              examples:
                response:
                  value: Successful operation.
        '400':
          description: Bad request
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Bad request:
                  value:
                    code: bad_request
                    message: Request body/path/query params cannot be validated.
                Article already exists:
                  value:
                    code: resource_cannot_be_created
                    message: article_id already exists.
                Invalid article(s):
                  value:
                    code: resource_cannot_be_created
                    message: Validation failed for one or more articles.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Articles
      summary: List all articles
      description: Returns a paginated list of all articles known within your organization account.
      operationId: listArticles
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: 'curl -X GET ''https://api.instock.com/v1/articles'' \

          -H ''Authorization: Bearer {ACCESS_TOKEN}''

          '
      parameters:
      - $ref: '#/components/parameters/instockCorrelationID'
      - $ref: '#/components/parameters/startCursor'
      - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Successful operation.
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listArticles'
              examples:
                List of articles:
                  $ref: '#/components/examples/listOfArticles'
        '400':
          description: Bad request
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Bad request:
                  value:
                    code: bad_request
                    message: Request body/path/query params cannot be validated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /articles/{article_id}:
    get:
      tags:
      - Articles
      summary: Retrieve article
      description: 'Retrieves a single existing article. Supply `article_id` either from article upload or articles list request,

        and Instock will return the corresponding article data.'
      operationId: getArticle
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: 'curl -X GET ''https://api.instock.com/v1/articles/{ARTICLE_ID}'' \

          -H ''Authorization: Bearer {ACCESS_TOKEN}''

          '
      parameters:
      - $ref: '#/components/parameters/instockCorrelationID'
      - $ref: '#/components/parameters/articleID'
      responses:
        '200':
          description: Successful operation
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/article'
              examples:
                Article:
                  $ref: '#/components/examples/RetrieveSingleArticle'
        '400':
          description: Bad request
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Bad request:
                  value:
                    code: bad_request
                    message: Request body/path/query params cannot be validated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not found
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Article doesn't exist:
                  value:
                    code: resource_not_found
                    message: article_id doesn't exist.
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Articles
      summary: Update article
      description: 'Updates a single existing article by setting the values of parameters passed.


        **Note**:

        * article update operation is performed via `PUT` method —

        when updating an article, a complete order record (all fields) must be passed.

        * if `article_id` has inventory moves, Incloud will yield `400` error.

        In other words, if an article has already been decanted into ASRS, its properties cannot be updated as

        Incloud already relies on its properties.'
      operationId: updateArticle
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X PUT 'https://api.instock.com/v1/articles/{ARTICLE_ID}' \\\n-H 'Authorization: Bearer {ACCESS_TOKEN}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"article_id\": \"016000124790\",\n  \"name\": \"Honey Nut Cheerios (10.8oz)\",\n  \"is_serial_numbered\": false,\n  \"dimensions\": {\n    \"x\": \"2\",\n    \"y\": \"7.7\",\n    \"z\": \"11.3\",\n    \"uom\": \"in\"\n  },\n  \"attributes\": {\n    \"product_category_name\": \"Cereals\",\n    \"temp_zone\": \"Ambient\",\n    \"promotion_price\": \"0.99\"\n  }\n}'\n"
      parameters:
      - $ref: '#/components/parameters/instockCorrelationID'
      - $ref: '#/components/parameters/articleID'
      requestBody:
        required: true
        description: Update a single existing article with properties in the request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/article'
            examples:
              Update an article:
                $ref: '#/components/examples/UpdateArticle'
      responses:
        '200':
          description: Successful operation.
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                type: string
              examples:
                response:
                  value: Successful operation.
        '400':
          description: Bad request
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Bad request:
                  value:
                    code: bad_request
                    message: Request body/path/query params cannot be validated.
                Article already has moves:
                  value:
                    code: resource_cannot_be_updated
                    message: Article cannot be updated as it already has moves.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not found
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Article doesn't exist:
                  value:
                    code: resource_not_found
                    message: article_id doesn't exist.
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    startCursor:
      name: start_cursor
      in: query
      required: false
      description: "Cursor returned from a previous response, \nused to request the next page of the results. \n"
      schema:
        type: string
        example: fe2cc560-036c-44cd-90e8-294d5a74cebc
        default: ''
    pageSize:
      name: page_size
      in: query
      required: false
      description: "The number of articles returned in response. \nDefault (minimum) value is 10, maximum value is 1000.\n"
      schema:
        type: integer
        format: int64
        example: 10
        default: 10
        maximum: 1000
    instockCorrelationID:
      name: Instock-Correlation-ID
      description: Optional header ID to track and analyze requests and behaviors across your Host system.
      in: header
      required: false
      schema:
        type: string
    articleID:
      name: article_id
      in: path
      description: ID of an article. Unique in scope of your organization(s).
      required: true
      schema:
        $ref: '#/components/schemas/articleId'
      example: 016000487727
  responses:
    InternalServerError:
      description: Internal server error
      headers:
        Instock-Response-ID:
          $ref: '#/components/headers/instockRequestID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: internal_server_error
            message: Unexpected error occurred.
    Unauthorized:
      description: Unauthorized
      headers:
        Instock-Response-ID:
          $ref: '#/components/headers/instockRequestID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unauthorized
            message: API key is not valid.
    Forbidden:
      description: Forbidden
      headers:
        Instock-Response-ID:
          $ref: '#/components/headers/instockRequestID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: forbidden
            message: API key doesn't have permissions to perform the request.
  examples:
    RetrieveSingleArticle:
      value:
        article_id: '116000487727'
        name: Cheerios Original Cereal, 12 Oz
        is_serial_numbered: false
        dimensions:
          x: '7.75'
          y: '12'
          z: '2.75'
          uom: in
        attributes:
          product_category_name: Cereals & Bars
          temp_zone: ambient
    MultipleArticles:
      value:
        articles:
        - article_id: '1003000031678'
          name: Quaker Apples and Cinnamon Instant Oatmeal Packets
          is_serial_numbered: false
          dimensions:
            x: '4.9'
            y: '7.9'
            z: '3.1'
            uom: m
          attributes:
            product_category_name: Cereals & Bars
            temp_zone: ambient
            promotion_price: '2.99'
        - article_id: '116000487727'
          name: Cheerios Original Cereal, 12 Oz
          is_serial_numbered: false
          dimensions:
            x: '7.75'
            y: '12'
            z: '2.75'
            uom: in
          attributes:
            product_category_name: Cereals & Bars
    SingleArticle:
      value:
        articles:
        - article_id: '116000487727'
          name: Cheerios Original Cereal, 12 Oz
          is_serial_numbered: false
          dimensions:
            x: '7.75'
            y: '12'
            z: '2.75'
            uom: in
          attributes:
            product_category_name: Cereals & Bars
            temp_zone: ambient
    UpdateArticle:
      value:
        article_id: '116000487727'
        name: Cheerios Original Cereal, 12 Oz
        is_serial_numbered: false
        dimensions:
          x: '7.75'
          y: '12'
          z: '2.75'
          uom: in
        attributes:
          product_category_name: Cereals & Bars
          temp_zone: ambient
          promotion_price: '1.69'
    listOfArticles:
      value:
        has_more: false
        next_cursor: ''
        articles:
        - article_id: '1003000031678'
          name: Quaker Apples and Cinnamon Instant Oatmeal Packets
          is_serial_numbered: false
          dimensions:
            x: '4.9'
            y: '7.9'
            z: '3.1'
            uom: m
          attributes:
            product_category_name: Cereals & Bars
            temp_zone: ambient
            promotion_price: '2.99'
        - article_id: '116000487727'
          name: Cheerios Original Cereal, 12 Oz
          is_serial_numbered: false
          dimensions:
            x: '7.75'
            y: '12'
            z: '2.75'
            uom: in
          attributes:
            product_category_name: Cereals & Bars
        - article_id: '116000275270'
          name: Cheerios Honey Nut Cereal, 12 Oz
          is_serial_numbered: false
          dimensions:
            x: '7.75'
            y: '12'
            z: '2.75'
            uom: in
          attributes:
            product_category_name: Cereals & Bars
  headers:
    instockRequestID:
      description: Auto-generated ID in the response headers to reference a specific request, useful for debugging or seeking support.
      schema:
        type: string
  schemas:
    listArticles:
      type: object
      properties:
        has_more:
          type: boolean
          description: 'If `true`, `next_cursor` to access next part of the list.

            If `false`, response includes the end of the list.

            '
        next_cursor:
          type: string
          description: "Only available when `has_more` is `true`.\nUsed to retrieve the next page of results by \npassing the value as the `start_cursor` parameter \nto the same endpoint.\n"
        articles:
          type: array
          items:
            type: object
            properties:
              article_id:
                $ref: '#/components/schemas/articleId'
              is_serial_numbered:
                type: boolean
                description: Is article serial numbered?
              name:
                type: string
                description: Name of an article.
              dimensions:
                description: Dimensions of an article.
                properties:
                  x:
                    type: string
                    description: Width.
                  y:
                    type: string
                    description: Height.
                  z:
                    type: string
                    description: Depth.
                  uom:
                    type: string
                    enum:
                    - m
                    - in
                    description: Units of measurement, meters or inches.
              attributes:
                type: object
                description: Custom attribute(s) added to a specific article.
                additionalProperties:
                  type: string
    Error:
      type: object
      properties:
        code:
          description: Code that identifies the reason of an error.
          type: string
        message:
          description: Description of an error.
          type: string
    article:
      type: object
      properties:
        article_id:
          $ref: '#/components/schemas/articleId'
        name:
          type: string
          description: Name of an article.
        is_serial_numbered:
          type: boolean
          description: Is article serial numbered?
          default: false
        dimensions:
          description: Dimensions of an article.
          properties:
            x:
              type: string
              description: Width.
            y:
              type: string
              description: Height.
            z:
              type: string
              description: Depth.
            uom:
              type: string
              enum:
              - m
              - in
              description: Units of measurement, meters or inches.
        attributes:
          type: object
          description: Custom attribute(s) added to a specific article.
          additionalProperties:
            type: string
    createArticles:
      type: object
      properties:
        articles:
          type: array
          items:
            type: object
            properties:
              article_id:
                $ref: '#/components/schemas/articleId'
              is_serial_numbered:
                type: boolean
                description: Is article serial numbered?
                default: false
              name:
                type: string
                description: Name of an article.
              dimensions:
                description: Dimensions of an article.
                properties:
                  x:
                    type: string
                    description: Width.
                  y:
                    type: string
                    description: Height.
                  z:
                    type: string
                    description: Depth.
                  uom:
                    type: string
                    enum:
                    - m
                    - in
                    description: Units of measurement, meters or inches.
              attributes:
                type: object
                description: Custom attribute(s) added to a specific article.
                additionalProperties:
                  type: string
    articleId:
      type: string
      description: ID of an article. Unique in scope of your organization(s).
      pattern: ^[a-zA-Z0-9_+.]+$
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      type: http
      scheme: bearer