Emporix Price lists API

openapi: 3.2.0
info:
  title: Emporix Price lists API
  version: ''
  contact:
    email: documentation@emporix.com
  description: 'Operations tagged Price lists across 2 of this provider''s published API definitions: emporix-price-service-openapi.yml, emporix-price-service-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
tags:
- name: Price lists
paths:
  /price/{tenant}/price-lists:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    get:
      tags:
      - Price lists
      summary: Retrieving all price lists
      description: Retrieves all price lists assigned to the tenant. You can filter the results with query parameters.
      security:
      - OAuth2:
        - price.pricelist_read
      parameters:
      - $ref: '#/components/parameters/trait_qParam'
      - $ref: '#/components/parameters/header_acceptLanguage'
      - $ref: '#/components/parameters/trait_paged_pageNumber'
      - $ref: '#/components/parameters/trait_paged_pageSize'
      - $ref: '#/components/parameters/trait_sort'
      - $ref: '#/components/parameters/trait_XTotalCount_header'
      - $ref: '#/components/parameters/query_priceLists_name'
      - $ref: '#/components/parameters/query_priceLists_effectiveDate'
      - $ref: '#/components/parameters/query_priceLists_currency'
      - $ref: '#/components/parameters/query_priceLists_country'
      - $ref: '#/components/parameters/query_priceLists_site'
      - $ref: '#/components/parameters/query_priceLists_customerGroup'
      - $ref: '#/components/parameters/query_priceLists_region'
      responses:
        '200':
          description: The request was successful. A list of price lists is returned.
          headers:
            X-Total-Count:
              schema:
                type: integer
              description: Total number of retrieved price lists.
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/priceList'
              examples:
                Response example:
                  $ref: '#/components/examples/priceLists_get_200_responseBody'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
      operationId: GET-price-retrieve-price-lists
    post:
      tags:
      - Price lists
      description: Creates a new price list.
      security:
      - OAuth2:
        - price.pricelist_manage
      summary: Creating a new price list
      operationId: POST-price-create-price-list
      parameters:
      - $ref: '#/components/parameters/header_contentLanguage'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/priceListCreation'
            examples:
              Price list with a customer group:
                $ref: '#/components/examples/priceLists_post_requestBody'
              Price list with a legal entity:
                $ref: '#/components/examples/priceLists_post_requestBody_legalEntity'
      responses:
        '201':
          description: The request was successful. The price list has been created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Price list's unique identifier.
              examples:
                Price list created:
                  value:
                    id: 6245a8f578a8576e338fa9c2
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
    servers:
    - url: https://api.emporix.io
  /price/{tenant}/price-lists/search:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    post:
      tags:
      - Price lists
      summary: Searching for price lists
      description: Searching for price lists assigned to the tenant.
      security:
      - OAuth2:
        - price.pricelist_read
      parameters:
      - $ref: '#/components/parameters/header_acceptLanguage'
      - $ref: '#/components/parameters/trait_paged_pageNumber'
      - $ref: '#/components/parameters/trait_paged_pageSize'
      - $ref: '#/components/parameters/trait_sort'
      - $ref: '#/components/parameters/trait_XTotalCount_header'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/searchRequest'
            examples:
              search for products:
                value:
                  q: id:example-id-1
      responses:
        '200':
          description: The request was successful. A list of price lists is returned.
          headers:
            X-Total-Count:
              schema:
                type: integer
              description: Total number of retrieved price lists.
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/priceList'
              examples:
                Response example:
                  $ref: '#/components/examples/priceLists_get_200_responseBody'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
      operationId: POST-price-search-price-lists
    servers:
    - url: https://api.emporix.io
  /price/{tenant}/price-lists/{priceListId}:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    - $ref: '#/components/parameters/path_priceListId'
    get:
      tags:
      - Price lists
      operationId: GET-price-retrieve-price-list
      summary: Retrieving a price list
      description: Retrieves a specified price list's details by priceListId.
      security:
      - OAuth2:
        - price.pricelist_read
      parameters:
      - $ref: '#/components/parameters/header_acceptLanguage'
      responses:
        '200':
          description: The request was successful. The price list is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/priceList'
              examples:
                Price List:
                  $ref: '#/components/examples/priceLists_priceListId_get_200'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          description: The requested price list could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorMessage'
              examples:
                Price List Not Found:
                  $ref: '#/components/examples/priceLists_priceListId_get_404'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
    put:
      tags:
      - Price lists
      operationId: PUT-price-update-price-list
      summary: Upserting a price list
      description: Updates a specified price list by priceListId, or creates a new one if a price list with the specified ID doesn't exist yet.
      security:
      - OAuth2:
        - price.pricelist_manage
      parameters:
      - $ref: '#/components/parameters/header_contentLanguage'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/priceListUpdate'
            examples:
              Update Price List:
                $ref: '#/components/examples/priceLists_put_requestBody'
      responses:
        '201':
          $ref: '#/components/responses/Created_201'
        '204':
          description: 'The request was successful. The price has been updated.

            '
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          description: The requested price list could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorMessage'
              examples:
                Price List Not Found:
                  $ref: '#/components/examples/priceLists_priceListId_put_404'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
    delete:
      summary: Deleting a price list
      operationId: DELETE-price-remove-price-list
      tags:
      - Price lists
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: false
      responses:
        '204':
          description: The request was successful. The price list has been deleted.
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
      description: 'Deletes a specified price list by priceListId.


        **Important**: All prices assigned to the price list are deleted as well, in an asynchronous manner.'
      security:
      - OAuth2:
        - price.pricelist_manage
    servers:
    - url: https://api.emporix.io
components:
  schemas:
    searchRequest:
      type: object
      properties:
        q:
          type: string
          description: "A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n"
    priceListCore:
      title: priceListCore
      type: object
      properties:
        currency:
          allOf:
          - $ref: '#/components/schemas/currency'
        countries:
          description: 'Codes of countries to which the price list applies, as defined in the Country Service.


            **Note** If not specified, the price list will be applicable to users from all locations.'
          type: array
          items:
            type: string
        regions:
          description: 'List of the regions to which the price list applies.


            **Note** If not specified, the price list will be applicable to users from all locations.'
          type: array
          items:
            type: string
        customerGroups:
          description: 'List of customer groups IDs for which the price list is valid. If not specified, the price list is applicable to all customer groups.


            **Note**: Customer groups cannot be provided if there is a legal entity specified for the price list.


            **The `customerGroups` field is in preview mode** - the system does not fully operate on the customer groups concept yet.'
          type: array
          items:
            allOf:
            - {}
            type: string
        legalEntityId:
          description: 'ID of the legal entity to which the price list applies.

            **Note**: Price list assigned to legal entity is also applicable for all the subsidiaries.'
          type: string
        siteCode:
          description: Code of the site to which the price list applies.
          type: string
        validity:
          allOf:
          - $ref: '#/components/schemas/dateValidity'
        mixins:
          type: object
          description: 'Map of custom price lists attributes.

            '
          additionalProperties: true
    metadata:
      type: object
      properties:
        createdAt:
          description: Date and time when the price was created.
          type: string
        modifiedAt:
          description: Date and time when the price was last modified.
          type: string
        version:
          minimum: 1
          type: integer
          description: Version of the price object. If provided optimistic locking will be enabled and it has to match version in the database
    priceListCreation:
      title: priceListCreation
      allOf:
      - type: object
        properties:
          id:
            type: string
            description: Custom price list identifier. If not provided, it is automatically generated.
          name:
            type: object
            description: 'Price list name. It should be a brief, human-readable name that describes the purpose of the price list, specified in a form of a map of translations.


              * If the `Content-Language` header is set to `*`, then the name should be provided as a map of translations, where each key is a language code and the value is the name in its respective language.

              * If the `Content-Language` header is set to a specific language, then the name should be provided as a map of single translation, where the key is a language code and the value is the name in its respective language.

              * If the `Content-Language` header is empty, then the name should be provided as a map of single translation, where the key is a language code and the value is the name in its respective language. The endpoint will asume that the name is provided in the default language defined in the Configuration Service.


              **Note**: You can provide the names only in languages defined in the Configuration Service. In case the name is provided in a language that is not defined in the Configuration Service, the request will be rejected.'
      - $ref: '#/components/schemas/priceListCore'
      - type: object
        properties:
          metadata:
            properties:
              mixins:
                type: object
                additionalProperties:
                  type: string
                description: Mixins schemas
      required:
      - siteCode
      - name
    errorMessage:
      type: object
      title: error
      description: Schema for API-specific errors.
      properties:
        code:
          minimum: 100
          maximum: 599
          description: Original HTTP error code, should be consistent with the response HTTP code.
          type: integer
        status:
          description: Original HTTP error reason.
          type: string
        message:
          description: Descriptive error message for debugging
          type: string
        details:
          description: List of problems causing this error.
          type: array
          items:
            title: errorDetail
            description: schema for specific error cause
            type: string
        errorCode:
          type: string
          description: Additional error code.
    priceListUpdate:
      title: priceListUpdate
      allOf:
      - $ref: '#/components/schemas/priceListCreation'
      - type: object
        properties:
          metadata:
            properties:
              version:
                type: number
                description: Current version of the object.
              mixins:
                type: object
                additionalProperties:
                  type: string
                description: Mixins schemas.
    dateValidity:
      type: object
      description: Date range in which the object is valid.
      properties:
        from:
          type: string
          description: Date from which the object is valid, compliant with the ISO 8601 standard.
        to:
          type: string
          description: Date to which the object is valid, compliant with the ISO 8601 standard.
    currency:
      type: string
      title: currency
      pattern: '[A-Z]{3}'
      description: Currency code, compliant with the ISO 4217 standard.
    priceList:
      title: priceList
      allOf:
      - type: object
        properties:
          id:
            type: string
            description: Unique identifier of the price that belongs to a price list, generated when the price is created and added to the price list.
          name:
            type: object
            description: Price list's name, expressed as a map of translations.
      - $ref: '#/components/schemas/priceListCore'
      - type: object
        properties:
          metadata:
            allOf:
            - $ref: '#/components/schemas/metadata'
            - type: object
              properties:
                mixins:
                  type: object
                  additionalProperties:
                    type: string
                  description: Mixins schemas
  examples:
    priceLists_get_200_responseBody:
      value:
      - id: example-id-1
        name:
          en: Example Price List 1
        currency: EUR
        countries:
        - PL
        customerGroups:
        - customer-group-1
        - customer-group-2
        siteCode: example-site-1
        validity:
          from: '2022-05-01T00:00:00.000Z'
          to: '2025-05-01T00:00:00.000Z'
        metadata:
          version: 1
          createdAt: '2022-03-31T13:18:02.379Z'
          modifiedAt: '2022-03-31T13:18:02.379Z'
      - id: example-id-2
        name:
          en: Example Price List 2
        currency: EUR
        regions:
        - DACH
        customerGroups:
        - customer-group-1
        siteCode: example-site-2
        metadata:
          version: 1
          createdAt: '2022-03-31T13:18:02.379Z'
          modifiedAt: '2022-03-31T13:18:02.379Z'
    priceLists_priceListId_put_404:
      value:
        priceListId: example-id-1
        code: 404
        status: Not Found
        message: 'Cannot find the price list with an id: example-id-1 and version: 1. It is possible to update a price list with the latest version only. Fetch the price list to get the latest version.'
    priceLists_priceListId_get_404:
      value:
        priceListId: example-id-1
        code: 404
        status: Not Found
        message: Price list with id example-id-1 has not been found.
    priceLists_post_requestBody_legalEntity:
      value:
        name:
          en: Example Price List 1
        currency: EUR
        legalEntityId: legal-entity-1
        siteCode: example-site-1
        validity:
          from: '2022-05-01T00:00:00.000Z'
          to: '2025-05-01T00:00:00.000Z'
    priceLists_post_requestBody:
      value:
        name:
          en: Example Price List 1
        currency: EUR
        countries:
        - PL
        customerGroups:
        - customer-group-1
        - customer-group-2
        siteCode: example-site-1
        validity:
          from: '2022-05-01T00:00:00.000Z'
          to: '2025-05-01T00:00:00.000Z'
    priceLists_put_requestBody:
      value:
        name:
          en: Example Price List 1
        currency: EUR
        countries:
        - DE
        customerGroups:
        - customer-group-3
        siteCode: example-site-1
        validity:
          from: '2022-05-01T00:00:00.000Z'
          to: '2025-05-01T00:00:00.000Z'
        metadata:
          version: 1
    priceLists_priceListId_get_200:
      value:
        id: example-id-1
        name:
          en: Example Price List 1
        currency: EUR
        countries:
        - PL
        customerGroups:
        - customer-group-1
        - customer-group-2
        siteCode: example-site-1
        validity:
          from: '2022-05-01T00:00:00.000Z'
          to: '2025-05-01T00:00:00.000Z'
        metadata:
          version: 1
          createdAt: '2022-03-31T13:18:02.379Z'
          modifiedAt: '2022-03-31T13:18:02.379Z'
  parameters:
    trait_paged_pageNumber:
      name: pageNumber
      in: query
      description: 'Page number to be retrieved. The number of the first page is 1.


        **Note:** If the `pageNumber` parameter is passed, size of the pages must be specified in the `pageSize` parameter.

        '
      schema:
        default: 1
        minimum: 1
        type: integer
    header_acceptLanguage:
      name: Accept-Language
      in: header
      required: false
      schema:
        type: string
      description: 'List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.

        * If the header is set to a particular language or a list of languages, all localized fields are retrieved as a map of single translation, where the key is a language code and the value is in a respective language.

        * If the header is set to `*`, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.

        * If the header is empty, localized fields are retrieved as maps of single translation, where the key is a language code and the value is in a respective language. The endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.

        '
    trait_XTotalCount_header:
      in: header
      name: X-Total-Count
      required: false
      description: Flag indicating whether the total count of retrieved items should be returned.
      schema:
        default: false
        type: boolean
    query_priceLists_region:
      name: region
      in: query
      required: false
      schema:
        type: string
      description: Code of the region to which the price list applies.
    query_priceLists_customerGroup:
      name: customerGroups
      in: query
      required: false
      schema:
        type: string
      description: Comma separated list of IDs of the customer groups to which the price list applies.
    path_priceListId:
      name: priceListId
      in: path
      required: true
      schema:
        type: string
      description: Price list's unique identifier, generated when the price list is created.
    query_priceLists_effectiveDate:
      name: effectiveDate
      in: query
      required: false
      schema:
        type: string
        example: '2022-01-01T00:00:00Z'
      description: Date on which retrieved prices should be valid, compliant with the ISO 8601 standard. Format:```date-fullyear "-" date-month "-" date-mday "T" partial-time time-offset```
    query_priceLists_currency:
      name: currency
      in: query
      required: false
      schema:
        type: string
      description: Code of the currency in which the prices are expressed, as defined in the Currency Service.
    trait_paged_pageSize:
      name: pageSize
      in: query
      description: 'Number of items to be retrieved per page.

        '
      schema:
        default: 60
        minimum: 1
        type: integer
    query_priceLists_name:
      name: name
      in: query
      required: false
      schema:
        type: string
      description: Price list's name.
    header_contentLanguage:
      name: Content-Language
      in: header
      required: false
      schema:
        type: string
      description: 'List of languages in which localized fields in the request body are provided.


        * If the `Content-Language` header is set to `*`, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.

        * If the `Content-Language` header is set to a specific language, then the localized fields should be provided as a map of single translation, where the key is a language code and the value is in a respective language.

        * If the `Content-Language` header is empty, then the localized fields should be provided as maps of single translation, where the key is a language code and the value is in a respective language. The endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.


        **Note**: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.

        '
    query_priceLists_site:
      name: siteCode
      in: query
      required: false
      schema:
        type: string
      description: Code of the site to which the price list applies.
    trait_sort:
      in: query
      name: sort
      required: false
      description: "List of properties used to sort the results, separated by colons. The order of properties indicates their priority in sorting.\n\nPossible values:\n* `{fieldName}`\n* `{fieldName}:asc`\n* `{fieldName}:desc`\n\n**Note:** If you want to sort the results by localized properties, the possible values are:\n  * `{fieldName}.{language}`\n  * `{fieldName}.{language}:asc`\n  * `{fieldName}.{language}:desc`\n\nIf the sorting direction is not specified, the fields are sorted in ascending order."
      schema:
        type: string
        example: name,code:desc
    trait_qParam:
      in: query
      name: q
      description: "A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n"
      schema:
        type: string
    trait_tenant:
      name: tenant
      in: path
      required: true
      description: 'Your Emporix tenant''s name.


        **Note**: The tenant should always be written in lowercase.

        '
      schema:
        pattern: ^[a-z][a-z0-9]+$
        minLength: 3
        maxLength: 16
        type: string
    query_priceLists_country:
      name: country
      in: query
      required: false
      schema:
        type: string
      description: Code of the country to which the price list applies, as defined in the Country Service.
  responses:
    InternalServiceError_500:
      description: Some server-side error occurred. Details are provided in the response payload.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Internal service error:
              value:
                code: 500
                status: Internal Server Error
                message: A server-side exception occurred that prevented the system from correctly returning the result.
    Created_201:
      description: The resource has been created.
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
                description: Identifier of a newly created item.
          examples:
            CreatedExample:
              value:
                id: 12345678-1234-1234-1234-123456789012
    Forbidden_403:
      description: Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Insufficient permissions:
              value:
                code: 403
                status: Forbidden
                message: The access to the requested resource has been forbidden by the server.
    Unauthorized_401:
      description: Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.
      content:
        application/json:
          schema:
            type: object
            properties:
              fault:
                type: object
                properties:
                  faultstring:
                    type: string
                  detail:
                    type: object
                    properties:
                      errorcode:
                        type: string
          examples:
            Invalid access token:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
            Access token expired:
              value:
                fault:
                  faultstring: Access Token expired
                  detail:
                    errorcode: keymanagement.service.access_token_expired
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.emporix.io/oauth/token
          scopes:
            price.price_manage: Needed to manage prices.
            price.price_read: Needed to retrieve prices.
            price.price_own: Needed to calculate product prices (legacy).
            price.prod_price_calculate: Needed to calculate prices and synchronize sale prices (legacy).
            price.price_delete_all: Needed to delete all prices at once (legacy).
            price.price_match_own: Needed to use the price matching functionality based on information from the session context.
            price.pricemodel_manage: Needed to manage price models.
            price.pricemodel_read: Needed to retrieve price models.
            price.price_manage_by_vendor: Needed to manage prices belonging to the vendor.
    CustomerAccessToken:
      type: http
      scheme: bearer
x-refined-from:
- emporix-price-service-openapi.yml
- emporix-price-service-openapi.yml