openapi: 3.0.1
tags:
  - name: Employees
    description: >
      Employees represent the personnel that are employed at a store and contain
      details such as contact

      information and the associated
      [store](/api/integration/inventory-management/store_api#tag/Stores).


      Use it to update and retrieve employees. Employees are created via the
      Identity Provider.
  - name: Stores
    description: >
      Represents a physical store in your business. It holds information on
      street and postal addresses,

      service hours, and delivery details.


      Use it to create, update, and retrieve stores.
info:
  title: Store operations
  contact:
    name: Team Store Fulfillment
    url: https://apidocs.newstore.io
  description: API for managing stores and related entities, such as employees.
  version: '0.1'
servers:
  - url: /v0/d
  - url: /
paths:
  /employees:
    x-pyramid-route-name: employees
    get:
      tags:
        - Employees
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Get all stores Response
                description: Response schema for getting all employees
                type: object
                properties:
                  employees:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee'
                required:
                  - employees
        '400':
          description: Incorrect request.
        '500':
          description: An internal error occurred.
        '503':
          description: Temporarily not available - service not available, try again later.
      description: >
        Retrieves the list of employees.


        **Related methods:**

        - [Get
        employee](/api/integration/inventory-management/store_api#tag/Employees/operation/getEmployee)

        - [Update
        employee](/api/integration/inventory-management/store_api#tag/Employees/operation/updateEmployee)
      summary: List employees
      operationId: listEmployees
  /employees/{employee_id}:
    x-pyramid-route-name: employee
    get:
      tags:
        - Employees
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '404':
          description: Employee not found.
        '500':
          description: An internal error occurred.
        '503':
          description: Temporarily not available - service not available, try again later.
      description: |
        Retrieves the employee"s details.
      summary: Get employee
      operationId: getEmployee
    patch:
      tags:
        - Employees
      responses:
        '200':
          description: ''
          headers:
            Warning:
              description: >
                Present when the request carried fields this endpoint does not
                apply.

                Carries warn-code `299` and the reason, for example:

                `299 - "Only store_id is applied by this endpoint. Identity
                fields are owned by user management (SSO) and were ignored."`
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeUpdateResult'
        '400':
          description: Bad request - Request data is invalid.
        '404':
          description: Employee not found.
        '409':
          description: >-
            Conflict - the employee was already updated by a concurrent request.
            Retry the request.
        '500':
          description: An internal error occurred.
        '503':
          description: Temporarily not available - service not available, try again later.
      description: >
        Assigns the employee to a store.


        Only `store_id` is applied. The employee's identity — `email`,
        `first_name`,

        `last_name`, `telephone_number` — and `is_active` are owned by your
        identity

        provider and are synchronized into NewStore from user management, so
        sending

        them here has no effect: they are accepted and ignored, and listed in

        `ignored_fields` in the response.


        To change an employee's name, email or phone number, change it in your

        identity provider. To deactivate an employee, block or remove the user
        in

        your identity provider — that clears the store assignment as well.


        No field is required. A request body of `{"store_id": "<store_id>"}` is

        enough to assign a store.
      summary: Assign employee to a store
      operationId: updateEmployee
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeStoreAssignment'
        required: true
    parameters:
      - name: employee_id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of an employee.
  /stores:
    x-pyramid-route-name: stores
    post:
      tags:
        - Stores
      responses:
        '200':
          description: |
            The store has been created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Store'
        '400':
          description: Bad Request - Request data is invalid.
        '404':
          description: Required data, such as catalogs are not found.
        '409':
          description: Conflict, requested store identifier already exists.
        '500':
          description: An internal error occurred.
        '503':
          description: Temporarily not available - service not available, try again later.
      description: >
        Creates a store. See the [Setting up a store
        tutorial](https://docs.newstore.com/docs/tutorial-setting-up-a-store).


        After you have created a store, you can:


        - [import stock into
        it](/api/integration/catalog-sfcc/import-api_api/#operation/stock).


        Ensure that you have [imported a price
        book](/api/integration/catalog-sfcc/import-api_api/#operation/price-books)

        before you assign it to a store. See the [Importing master data
        tutorial](https://docs.newstore.com/v1/docs/importing-data#integ-importdata).


        To set up a shipping strategy for the store, including shipping methods,
        provider rates, and routes,

        [create a fulfillment
        configuration](/api/integration/order-management/newstore_ff_config_api#operation/add-or-update-fulfillment-configuration).

        See the [fulfillment config
        tutorial](https://docs.newstore.com/v1/docs/tutorial-setting-up-a-fulfillment-configuration#tutorial_fulfillment-config-new).


        By default a fulfillment location will also be created with the same id
        as the store's id. If you are using custom fulfilment location IDs,

        then you will need to: [create the fulfillment
        location](https://docs.newstore.com/v1/docs/tutorial-importing-stock-information#optional-creating-a-fulfillment-location-with-a-custom-id)
        with its custom ID so that Store Fulfillment

        can work with your store after creating the Store.


        **Related methods:**

        - [Get
        store](/api/integration/inventory-management/store_api#tag/Stores/operation/getStore)

        - [List
        stores](/api/integration/inventory-management/store_api#tag/Stores/operation/listStores)
      summary: Create store
      operationId: createStore
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Store'
              required:
                - label
                - store_id
                - timezone
                - physical_address
                - delivery_zip_codes
                - display_price_unit_type
                - tax_included
        required: true
    get:
      tags:
        - Stores
      parameters:
        - in: query
          name: lat
          schema:
            type: number
          required: false
          description: >-
            Used if you want to fetch nearby stores. You must provide both
            latitude and longitude to query by location.
        - in: query
          name: long
          schema:
            type: number
          required: false
          description: >-
            Used if you want to fetch nearby stores. You must provide both
            latitude and longitude to query by location.
        - in: query
          name: radius
          schema:
            type: number
          required: false
          description: >-
            Used if you want to fetch nearby stores. Given a set of coordinates,
            only stores within this distance (in meters) will be returned.
        - in: query
          name: max_stores
          schema:
            type: number
          required: false
          description: >-
            Used if you want to fetch nearby stores. Maximum number of stores
            returned when fetching by location. Latitude and longitude
            parameters are mandatory.
      responses:
        '200':
          description: |
            Successful response.
          content:
            application/json:
              schema:
                title: Get all stores Response
                description: Response schema for getting all stores
                type: object
                properties:
                  stores:
                    type: array
                    items:
                      $ref: '#/components/schemas/Store'
                required:
                  - stores
        '400':
          description: Bad Request - Request data is invalid.
        '500':
          description: An internal error occurred.
        '503':
          description: Temporarily not available - Service not available, try again later.
      description: >
        Retrieves the list of stores.


        **Related methods:**

        - [Get
        store](/api/integration/inventory-management/store_api#tag/Stores/operation/getStore)

        - [Update
        store](/api/integration/inventory-management/store_api#tag/Stores/operation/updateStore)

        - [Create
        store](/api/integration/inventory-management/store_api#tag/Stores/operation/createStore)
      summary: List stores
      operationId: listStores
  /stores/{store_id}:
    x-pyramid-route-name: store
    get:
      tags:
        - Stores
      responses:
        '200':
          description: |
            Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Store'
        '400':
          description: Request data is invalid.
        '404':
          description: Store not found.
        '500':
          description: An internal error occurred.
        '503':
          description: Temporarily not available - service not available, try again later.
      description: |
        Gets the store and all its detailed information.
      summary: Get store
      operationId: getStore
    patch:
      tags:
        - Stores
      responses:
        '200':
          description: |
            The store has been updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Store'
        '400':
          description: Request data is invalid.
        '404':
          description: Store not found.
        '500':
          description: An internal error occurred.
        '503':
          description: Temporarily not available - service not available, try again later.
      description: >
        Updates the store. Only attributes supplied in the request are changed.


        **Note**: When you deactivate a store, ensure that the store has no
        employees assigned to it.

        To prevent routing orders to deactivated stores, also [contact NewStore
        support](https://support.newstore.com)

        to ensure that:

        - there is no stock left in the store.

        - the fulfillment configuration is updated to remove the
        `fulfillment_node_id` matching the store.


        **Related methods:**

        - [Create
        store](/api/integration/inventory-management/store_api#tag/Stores/operation/createStore)
      summary: Update store
      operationId: updateStore
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Store'
        required: true
    parameters:
      - name: store_id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of a store.
  /stores/{store_id}/employees:
    x-pyramid-route-name: store_employees
    get:
      tags:
        - Employees
      responses:
        '200':
          description: |
            Successful response.
          content:
            application/json:
              schema:
                properties:
                  employees:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee'
        '400':
          description: Request data is invalid.
        '404':
          description: Store not found.
        '500':
          description: An internal error occurred.
        '503':
          description: Temporarily not available - service not available, try again later.
      description: |
        Gets all employees belonging to a store.
      summary: Get store employees
      operationId: getStoreEmployees
    parameters:
      - name: store_id
        in: path
        required: true
        schema:
          type: string
        description: The identifier of the store.
components:
  securitySchemes:
    newStoreAccessToken:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    Employee:
      title: Employee
      description: Represents an employee - can be a store associate or a manager
      required:
        - email
        - first_name
        - last_name
        - telephone_number
      type: object
      properties:
        id:
          type: string
          maxLength: 36
          example: 4vpg8bG5iilWGkyCkUpwb0
        email:
          maxLength: 256
          type: string
          example: jay.doubleyou@example.com
        first_name:
          maxLength: 256
          type: string
          example: Jay
        last_name:
          maxLength: 256
          type: string
          example: DoubleYou
        telephone_number:
          maxLength: 32
          type: string
          example: 202-111-2367
        store_id:
          minLength: 1
          maxLength: 256
          type: string
          nullable: true
          example: 78b4fc81-d4a2-5edd-84d9-149a84312400
        image_url:
          type: string
          nullable: true
          maxLength: 256
          example: www.test-image-url.com
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        store:
          type: object
          nullable: true
          properties:
            label:
              type: string
              minLength: 1
        printer_location:
          type: object
          nullable: true
          description: >
            Read-only. Carries the printer location on employees that hold one;
            no

            endpoint sets or clears it.
          properties:
            uuid:
              type: string
              minLength: 36
              maxLength: 36
            name:
              type: string
              minLength: 1
        is_active:
          type: boolean
          example: true
    EmployeeStoreAssignment:
      title: EmployeeStoreAssignment
      description: |
        Request body of `PATCH /employees/{employee_id}`.

        `store_id` is the only field applied. Any other field — including the
        identity fields of the `Employee` schema — is accepted so that existing
        integrations keep working, and ignored.
      type: object
      additionalProperties: true
      properties:
        store_id:
          minLength: 1
          maxLength: 256
          type: string
          nullable: true
          description: The store to assign the employee to.
          example: 78b4fc81-d4a2-5edd-84d9-149a84312400
    EmployeeUpdateResult:
      title: EmployeeUpdateResult
      description: |
        The employee after the update, plus which of the submitted fields were
        applied and which were ignored.
      allOf:
        - $ref: '#/components/schemas/Employee'
        - type: object
          properties:
            applied_fields:
              type: array
              description: Submitted fields that were written to the employee.
              items:
                type: string
              example:
                - store_id
            ignored_fields:
              type: array
              description: |
                Submitted fields that were discarded because this endpoint does
                not own them.
              items:
                type: string
              example:
                - email
                - first_name
                - last_name
                - telephone_number
    Store:
      title: Store
      description: Store entity.
      type: object
      properties:
        label:
          maxLength: 256
          type: string
          example: 001_US_ABC_Street
        physical_address:
          nullable: false
          description: Represents an address
          required:
            - address_line_1
            - country_code
          title: Address
          type: object
          properties:
            address_line_1:
              type: string
            address_line_2:
              type: string
              nullable: true
            province:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
            zip_code:
              maxLength: 256
              type: string
              nullable: true
            city:
              maxLength: 256
              type: string
              nullable: true
            country_code:
              $ref: '#/components/schemas/CountryCode'
            latitude:
              type: number
              nullable: true
            longitude:
              type: number
              nullable: true
          example:
            address_line_1: 12 ABC Street
            city: New York
            country_code: US
            latitude: 40.7256956
            longitude: -74.0023217
            state: NY
            zip_code: '10001'
        shipping_address:
          nullable: true
          description: Represents an address
          required:
            - address_line_1
            - country_code
          example:
            address_line_1: 12 ABC Street
            city: New York
            country_code: US
            state: NY
            zip_code: '10002'
          title: Address
          type: object
          properties:
            address_line_1:
              type: string
            address_line_2:
              type: string
              nullable: true
            province:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
            zip_code:
              maxLength: 256
              type: string
              nullable: true
            city:
              maxLength: 256
              type: string
              nullable: true
            country_code:
              $ref: '#/components/schemas/CountryCode'
            latitude:
              type: number
              nullable: true
            longitude:
              type: number
              nullable: true
        division_name:
          type: string
          nullable: true
          description: Division of the company this store belongs to.
          example: US
        manager_id:
          maxLength: 36
          type: string
          nullable: true
          example: 466ba016-42d4-47cb-a953-0b808c949b64
        image_url:
          type: string
          nullable: true
          example: www.image-url.com
        phone_number:
          type: string
          nullable: true
          description: The telephone number at which the store can be reached.
          example: 202-555-0138
        active_status:
          type: boolean
          description: >-
            Whether the store is active in the business. This is an
            informational flag: Omnichannel Manager, Associate App and store
            locators use it to hide inactive stores from store selectors. It
            does not control order routing or ATP. To stop a location from
            receiving fulfillment orders, disable the location via the Location
            API instead.
          example: true
        supported_shipping_methods:
          type: array
          items:
            enum:
              - traditional_carrier
              - same_day_delivery
              - in_store_pick_up
              - in_store_handover
            type: string
          example:
            - in_store_pick_up
        gift_wrapping:
          type: boolean
          example: false
        pricebook:
          type: string
          nullable: true
          description: >-
            Identifier of a pricebook which should be used for this store. The
            pricebook defines prices for all products sold in the store. If a
            pricebook is not specified, a default pricebook will be used by the
            store.
          example: dodici-ca
        delivery_zip_codes:
          type: array
          items:
            type: string
            minLength: 2
            maxLength: 32
          example:
            - '10001'
            - '10002'
        shipping_provider_info:
          type: object
          description: >-
            Shipping provider information containing all external provider (like
            zip codes, the external store id and so on).
        business_hours:
          type: array
          items:
            type: object
            description: Represents store business hours information
            required:
              - from_time
              - to_time
              - weekday
            properties:
              from_time:
                type: string
                pattern: ^\d{2}:\d{2}$
              to_time:
                type: string
                pattern: ^\d{2}:\d{2}$
              weekday:
                type: integer
                description: Value represents week day starting from Monday
              earliest_pick_up:
                type: string
                nullable: true
                pattern: ^\d{2}:\d{2}$
              latest_pick_up:
                type: string
                nullable: true
                pattern: ^\d{2}:\d{2}$
          example:
            - from_time: '09:00'
              to_time: '21:00'
              earliest_pick_up: '10:00'
              latest_pick_up: '20:00'
              weekday: 0
            - from_time: '09:00'
              to_time: '20:00'
              earliest_pick_up: '10:00'
              latest_pick_up: '20:00'
              weekday: 1
            - from_time: '09:00'
              to_time: '20:00'
              earliest_pick_up: '10:00'
              latest_pick_up: '20:00'
              weekday: 2
            - from_time: '09:00'
              to_time: '20:00'
              earliest_pick_up: '10:00'
              latest_pick_up: '20:00'
              weekday: 3
            - from_time: '09:00'
              to_time: '20:00'
              earliest_pick_up: '10:00'
              latest_pick_up: '20:00'
              weekday: 4
            - from_time: '09:00'
              to_time: '20:00'
              earliest_pick_up: '10:00'
              latest_pick_up: '20:00'
              weekday: 5
            - from_time: '09:00'
              to_time: '20:00'
              earliest_pick_up: '10:00'
              latest_pick_up: '20:00'
              weekday: 6
        timezone:
          type: string
          maxLength: 256
          description: >
            Only allows timezone values that comply with the <a
            href="https://en.wikipedia.org/wiki/Tz_database">tz database</a>.
          example: America/New_York
        tax_id:
          type: string
          nullable: true
          minLength: 9
          maxLength: 9
          example: null
        tax_included:
          type: boolean
          description: If true, the prices associated with this store include tax.
          example: true
        catalog:
          type: string
          nullable: true
          maxLength: 256
          description: >-
            The name of the catalog containing the list of products that can be
            sold at this store.
          example: storefront-catalog-en
        locale:
          type: string
          nullable: true
          maxLength: 32
          description: >-
            The locale of the catalog assigned to the store. The product data in
            the catalog is displayed based on the locale specified here.
          example: en-US
        store_id:
          minLength: 1
          maxLength: 256
          type: string
          example: 050_Mc_Avenue
          pattern: ^[a-zA-Z0-9_-]*$
          description: store id (only for store creation)
        display_price_unit_type:
          type: string
          enum:
            - net
            - gross
          example: gross
        revision:
          type: integer
          example: 1
          readOnly: true
        updated_at:
          format: date-time
          readOnly: true
        created_at:
          format: date-time
          readOnly: true
    CountryCode:
      description: >-
        Country code for this address. Must be <a
        href="http://www.iso.org/iso/country_codes.htm">ISO-3166 reference</a>.
      type: string
      example: US
      enum:
        - AD
        - AE
        - AF
        - AG
        - AI
        - AL
        - AM
        - AO
        - AQ
        - AR
        - AS
        - AT
        - AU
        - AW
        - AX
        - AZ
        - BA
        - BB
        - BD
        - BE
        - BF
        - BG
        - BH
        - BI
        - BJ
        - BL
        - BM
        - BN
        - BO
        - BQ
        - BR
        - BS
        - BT
        - BV
        - BW
        - BY
        - BZ
        - CA
        - CC
        - CD
        - CF
        - CG
        - CH
        - CI
        - CK
        - CL
        - CM
        - CN
        - CO
        - CR
        - CU
        - CV
        - CW
        - CX
        - CY
        - CZ
        - DE
        - DJ
        - DK
        - DM
        - DO
        - DZ
        - EC
        - EE
        - EG
        - EH
        - ER
        - ES
        - ET
        - FI
        - FJ
        - FK
        - FM
        - FO
        - FR
        - GA
        - GB
        - GD
        - GE
        - GF
        - GG
        - GH
        - GI
        - GL
        - GM
        - GN
        - GP
        - GQ
        - GR
        - GS
        - GT
        - GU
        - GW
        - GY
        - HK
        - HM
        - HN
        - HR
        - HT
        - HU
        - ID
        - IE
        - IL
        - IM
        - IN
        - IO
        - IQ
        - IR
        - IS
        - IT
        - JE
        - JM
        - JO
        - JP
        - KE
        - KG
        - KH
        - KI
        - KM
        - KN
        - KP
        - KR
        - KW
        - KY
        - KZ
        - LA
        - LB
        - LC
        - LI
        - LK
        - LR
        - LS
        - LT
        - LU
        - LV
        - LY
        - MA
        - MC
        - MD
        - ME
        - MF
        - MG
        - MH
        - MK
        - ML
        - MM
        - MN
        - MO
        - MP
        - MQ
        - MR
        - MS
        - MT
        - MU
        - MV
        - MW
        - MX
        - MY
        - MZ
        - NA
        - NC
        - NE
        - NF
        - NG
        - NI
        - NL
        - 'NO'
        - NP
        - NR
        - NU
        - NZ
        - OM
        - PA
        - PE
        - PF
        - PG
        - PH
        - PK
        - PL
        - PM
        - PN
        - PR
        - PS
        - PT
        - PW
        - PY
        - QA
        - RE
        - RO
        - RS
        - RU
        - RW
        - SA
        - SB
        - SC
        - SD
        - SE
        - SG
        - SH
        - SI
        - SJ
        - SK
        - SL
        - SM
        - SN
        - SO
        - SR
        - SS
        - ST
        - SV
        - SX
        - SY
        - SZ
        - TC
        - TD
        - TF
        - TG
        - TH
        - TJ
        - TK
        - TL
        - TM
        - TN
        - TO
        - TR
        - TT
        - TV
        - TW
        - TZ
        - UA
        - UG
        - UM
        - US
        - UY
        - UZ
        - VA
        - VC
        - VE
        - VG
        - VI
        - VN
        - VU
        - WF
        - WS
        - YE
        - YT
        - ZA
        - ZM
        - ZW
x-annotation-crossOriginAllowed: true
