Emporix Price models API

openapi: 3.2.0
info:
  title: Emporix Price models API
  version: ''
  contact:
    email: documentation@emporix.com
  description: 'Operations tagged Price models 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 models
paths:
  /price/{tenant}/priceModels:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    post:
      summary: Creating a new price model
      description: 'Creates a new price model.


        A price model can be defined as a repeatable way to sell products in a market with the intention of making a profit. Price models define basic structures for prices, including whether the prices are expressed as gross or net or the measurement units for which prices are defined.


        Each price model can specify one of three pricing strategies:

        * Basic pricing, where the price per unit is constant, regardless of the ordered quantity.

        * Volume pricing, where the price per unit depends on the ordered quantity.

        * Tiered pricing, where the price per unit depends on the tiers that the ordered quantity falls into.'
      security:
      - OAuth2:
        - price.pricemodel_manage
      parameters:
      - $ref: '#/components/parameters/trait_contentLanguage_header'
      responses:
        '201':
          description: The request was successful. The price model has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/priceModelDefinitionCreationResponse'
        '400':
          $ref: '#/components/responses/BadRequest_400'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      tags:
      - Price models
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/priceModelDefinitionCreation'
            examples:
              Basic price model with localized attributes:
                value:
                  includesTax: true
                  includesMarkup: true
                  name: Piece price model
                  description: Sample description
                  tierDefinition:
                    tierType: BASIC
                    tiers:
                    - minQuantity:
                        quantity: 0
                        unitCode: pc
                  measurementUnit:
                    quantity: 0
                    unitCode: pc
              Basic price model with a map of localized attributes:
                value:
                  includesTax: true
                  includesMarkup: true
                  name:
                    en: Piece price model
                    de: Stueck price model
                  description:
                    en: Sample description
                    de: Beispielbeschreibung
                  tierDefinition:
                    tierType: BASIC
                    tiers:
                    - minQuantity:
                        quantity: 0
                        unitCode: pc
                  measurementUnit:
                    quantity: 0
                    unitCode: pc
              Tiered price model with a map of localized attributes:
                value:
                  name:
                    en: Tiered pricing - per kilogram
                  description:
                    en: Tiered price model for goods sold by the kilogram.
                  includesTax: true
                  includesMarkup: false
                  measurementUnit:
                    quantity: 1
                    unitCode: kg
                  tierDefinition:
                    tierType: TIERED
                    tiers:
                    - minQuantity:
                        quantity: 0
                        unitCode: kg
                    - minQuantity:
                        quantity: 5
                        unitCode: kg
                    - minQuantity:
                        quantity: 10
                        unitCode: kg
              Volume price model with a map of localized attributes:
                value:
                  name:
                    en: Volume pricing - per 100 gram
                  description:
                    en: Volume price model for goods sold by 100 gram.
                  includesTax: true
                  includesMarkup: false
                  measurementUnit:
                    quantity: 100
                    unitCode: g
                  tierDefinition:
                    tierType: VOLUME
                    tiers:
                    - minQuantity:
                        quantity: 0
                        unitCode: g
                    - minQuantity:
                        quantity: 500
                        unitCode: g
                    - minQuantity:
                        quantity: 1000
                        unitCode: g
      operationId: POST-price-create-price-model
    get:
      summary: Retrieving all price models
      description: 'Retrieves all price models assigned to the tenant. You can filter the results with query parameters.


        A price model can be defined as a repeatable way to sell products in a market with the intention of making a profit. Price models define basic structures for prices.'
      security:
      - OAuth2:
        - price.pricemodel_read
      parameters:
      - $ref: '#/components/parameters/trait_acceptLanguage_header'
      - $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/trait_priceModel_includesTax'
      - $ref: '#/components/parameters/trait_priceModel_includesMarkup'
      - $ref: '#/components/parameters/trait_priceModel_tierType'
      - $ref: '#/components/parameters/trait_priceModel_name'
      - $ref: '#/components/parameters/trait_priceModel_description'
      - $ref: '#/components/parameters/trait_priceModel_unitcode'
      responses:
        '200':
          description: The request was successful. A list of price models is returned.
          headers:
            X-Total-Count:
              schema:
                type: integer
              description: Total number of retrieved price models.
          content:
            application/json:
              examples:
                Response example:
                  value:
                  - id: 6245a8f578a8576e338fa9c2
                    name: Tiered price model
                    includesTax: true
                    includesMarkup: true
                    default: true
                    measurementUnit:
                      quantity: 50
                      unitCode: g
                    tierDefinition:
                      tierType: TIERED
                      tiers:
                      - minQuantity:
                          quantity: 0
                          unitCode: g
                      - minQuantity:
                          quantity: 100
                          unitCode: g
                      - minQuantity:
                          quantity: 500
                          unitCode: g
                    metadata:
                      version: 1
                      createdAt: '2022-03-31T13:13:25.816Z'
                      modifiedAt: '2022-03-31T13:13:25.816Z'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/priceModelDefinitionRetrieval'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/priceModelDefinitionRetrieval'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      tags:
      - Price models
      operationId: GET-price-list-price-models
    servers:
    - url: https://api.emporix.io
  /price/{tenant}/priceModels/{priceModelId}:
    parameters:
    - schema:
        type: string
      name: tenant
      in: path
      required: true
      description: 'Your Emporix tenant''s name.


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

        '
    - schema:
        type: string
      name: priceModelId
      in: path
      required: true
      description: Price model's unique identifier, generated when the price model is created.
    get:
      summary: Retrieving a price model
      description: 'Retrieves a specified price model''s details by priceModelId.


        A price model can be defined as a repeatable way to sell products in a market with the intention of making a profit. Price models define basic structures for prices.'
      security:
      - OAuth2:
        - price.pricemodel_read
      parameters:
      - $ref: '#/components/parameters/trait_acceptLanguage_header'
      responses:
        '200':
          description: The request was successful. The price model is returned.
          content:
            application/json:
              examples:
                Response example:
                  value:
                  - id: 6245a8f578a8576e338fa9c2
                    name: Tiered price model
                    includesTax: true
                    includesMarkup: true
                    measurementUnit:
                      quantity: 50
                      unitCode: g
                    tierDefinition:
                      tierType: TIERED
                      tiers:
                      - minQuantity:
                          quantity: 0
                          unitCode: g
                      - minQuantity:
                          quantity: 100
                          unitCode: g
                      - minQuantity:
                          quantity: 500
                          unitCode: g
                    metadata:
                      version: 1
                      createdAt: '2022-03-31T13:13:25.816Z'
                      modifiedAt: '2022-03-31T13:13:25.816Z'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/priceModelDefinitionRetrieval'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/priceModelDefinitionRetrieval'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          $ref: '#/components/responses/NotFound_404'
      tags:
      - Price models
      operationId: GET-price-retrieve-price-model
    put:
      summary: Upserting a price model
      description: Updates a specified price model's details by priceModelId, or creates a new one if a price model with the specified ID doesn't exist yet.
      operationId: PUT-price-update-price-model
      security:
      - OAuth2:
        - price.pricemodel_manage
      responses:
        '201':
          $ref: '#/components/responses/Created_201'
        '204':
          description: 'The request was successful. The price has been updated.

            '
        '400':
          $ref: '#/components/responses/BadRequest_400'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          $ref: '#/components/responses/NotFound_404'
      tags:
      - Price models
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/priceModelDefinitionCreation'
            examples:
              Request example:
                value:
                  id: 6245a8f578a8576e338fa9c2
                  name: Tiered price model
                  includesTax: true
                  includesMarkup: true
                  measurementUnit:
                    quantity: 50
                    unitCode: g
                  tierDefinition:
                    tierType: TIERED
                    tiers:
                    - minQuantity:
                        quantity: 0
                        unitCode: g
                    - minQuantity:
                        quantity: 100
                        unitCode: g
                    - minQuantity:
                        quantity: 500
                        unitCode: g
                  metadata:
                    version: 1
        description: ''
      parameters:
      - $ref: '#/components/parameters/trait_contentLanguage_header'
    delete:
      summary: Deleting a price model
      operationId: DELETE-price-remove-price-model
      description: 'Deletes a specified price model by priceModel Id.


        **Important**: If you want to delete a price model that has prices assigned to it, you need to set the `forceDelete` query parameter to `true`. In this case, all prices assigned to the price model are deleted as well, in an asynchronous manner.


        **Additional scopes info**

        The `price.pricemodel_manage_admin` scope is only required if you want to delete a price model that has prices assigned to it.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: false
      parameters:
      - schema:
          type: boolean
        in: query
        name: forceDelete
        description: "* If set to `true` and the price model has prices assigned to it, both the price model and the prices will be deleted.\n\n  **Important**: To set this parameter to `true`, your access token needs to have the `price.pricemodel_manage_admin` scope granted.\n* If set to `false` or not specified and the price model has prices assigned to it, the endpoint will respond with a `400` error."
      security:
      - OAuth2:
        - price.pricemodel_manage
        - price.pricemodel_manage_admin
      responses:
        '204':
          description: The request was successful. The price model has been deleted.
        '400':
          $ref: '#/components/responses/BadRequest_400'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      tags:
      - Price models
    servers:
    - url: https://api.emporix.io
components:
  schemas:
    tierDetailsDefinitionCreation:
      type: object
      description: 'Quantity that indicates the tier''s range:

        * The `minQuantity` of the tier defines the left side of the range (inclusive).

        * The `minQuantity` of the next tier defines the right side of the range (exclusive).

        '
      properties:
        id:
          type: string
          description: 'An identifier of the tier. If the value is not provided then it is automatically generated. The id is used during an update operation for recognizing whether a particular tier has been changed, removed or added. '
        minQuantity:
          allOf:
          - $ref: '#/components/schemas/measurementUnit'
          - type: object
            description: Minimum quantity of the product from which the tier applies.
      required:
      - minQuantity
    priceModelDefinitionCreationResponse:
      title: priceModelDefinitionCreationResponse
      type: object
      description: ''
      properties:
        id:
          type: string
          description: Price model's unique identifier.
    measurementUnit:
      type: object
      description: Measurement unit for which the price is defined.
      properties:
        quantity:
          minimum: 0
          description: Quantity of the measurement unit.
          type: number
        unitCode:
          description: Code of the measurement unit, as defined in the Unit Handling Service.
          type: string
      required:
      - quantity
      - unitCode
      title: ''
    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.
    priceModelDefinitionRetrieval:
      title: priceModelDefinitionRetrieval
      type: object
      description: A price model can be defined as a repeatable way to sell products in a market with the intention of making a profit. Price models define basic structures for prices.
      properties:
        id:
          type: string
          description: Price model's unique identifier, generated when the price model is created.
        includesTax:
          type: boolean
          description: 'Flag indicating whether prices assigned to the price model are expressed as net or gross.


            | Value | Description |

            | --- | --- |

            | `true` | Prices are expressed as gross values. |

            | `false` | Prices are expressed as net values. |

            '
        includesMarkup:
          type: boolean
          description: 'Flag indicating whether prices assigned to the price model include markup.


            **The `includesMarkup` field is in preview mode** - some of the features may not be fully operational yet.

            '
        default:
          type: boolean
          description: Indicates whether the price model is default one or not.
        name:
          description: Price model name.
          oneOf:
          - type: object
          - type: string
        description:
          description: Price model description.
          oneOf:
          - type: object
          - type: string
        tierDefinition:
          allOf:
          - $ref: '#/components/schemas/tierDefinitionCreation'
          - type: object
            description: Definition of pricing tiers.
        measurementUnit:
          allOf:
          - $ref: '#/components/schemas/measurementUnit'
          - type: object
            description: 'Measurement unit and quantity for which the price is defined.


              For example, if a product is sold by the piece, the field should contain `1 pc`. If products for this price model are sold per kilogram, this field should contain `1kg`.

              '
    tierDefinitionCreation:
      type: object
      properties:
        tierType:
          type: string
          description: "Possible values:\n* `BASIC`\n* `VOLUME`\n* `TIERED`\n\n`BASIC`: Used to offer the same price per unit, regardless of the ordered quantity.\n\n  **Note**: When using basic pricing, you need to define a single tier and set its `minQuantity` field to `0`.\n\n`VOLUME`: Used to offer a lower price per unit depending on the total ordered quantity.\n\n`TIERED`: Used to offer a lower price per unit based on the tiers that the total ordered quantity falls into.\n\n  **Example**: You defined three tiers, starting at 5, 10, and 15 pieces respectively. A customer orders 16 pieces. In this pricing model, the first 5 pieces will be priced according to the first tier, the next 5 according to the second tier, and the 16th piece will be priced according to the third tier."
        tiers:
          type: array
          description: "Tier quantities.\n\nEach tier contains information about the minimum quantity from which it (and its price) is valid.\n\n**Example**: For two tiers with the following `minQuantity` values: 0 pieces and 10 pieces, the effective ranges will be `<0, 9)` and `<10, infinity)`.\n\n**Note**: When defining tiers, be aware of the following restrictions to the `PriceModel` object:\n* For `BASIC` tier type:\n  * Only one tier should be defined. If the tier is not defined, it will be automatically generated.\n  * The tier's `minQuantity.quantity` should be set to `0`.\n* For `VOLUME` and `TIERED` type:\n  * Each `minQuantity.quantity` field must contain a unique value.\n  * The tiers must be defined in an ascending order based on their `quantity` value.\n  * The `quantity` field in the first tier must be set to `0`.\n  * All `unitCode` fields must contain the same value."
          items:
            allOf:
            - $ref: '#/components/schemas/tierDetailsDefinitionCreation'
      required:
      - tierType
    priceModelDefinitionCreation:
      title: priceModelDefinitionCreation
      type: object
      description: A price model can be defined as a repeatable way to sell products in a market with the intention of making a profit. Price models define basic structures for prices.
      properties:
        id:
          type: string
          description: Custom price model identifier. If not provided, it is automatically generated.
        includesTax:
          type: boolean
          description: 'Flag indicating whether prices assigned to the price model will be expressed as net or gross.


            | Value | Description |

            | --- | --- |

            | `true` | Prices will be expressed as gross values. |

            | `false` | Prices will be expressed as net values. |

            '
        includesMarkup:
          type: boolean
          description: 'Flag indicating whether prices assigned to the price model include markup.


            **The `includesMarkup` field is in preview mode** - some of the features may not be fully operational yet.'
        default:
          type: boolean
          description: Indicates whether the price model is default one or not.
        name:
          description: 'Price model name. It should be a brief, human-readable name that describes purposes of the model.


            * 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, the name should be provided as a string.

            * If the `Content-Language` header is empty, 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.'
          oneOf:
          - type: object
          - type: string
        description:
          description: 'Price model description. It can contain details about the price model.


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

            * If the `Content-Language` header is set to a specific language, the description should be provided as a string.

            * If the `Content-Language` header is empty, the endpoint will asume that the description is provided in the default language defined in the Configuration Service.


            **Note**: You can provide the descriptions only in languages defined in the Configuration Service. In case the description is provided in a language that is not defined in the Configuration Service, the request will be rejected.'
          oneOf:
          - type: object
          - type: string
        tierDefinition:
          allOf:
          - $ref: '#/components/schemas/tierDefinitionCreation'
          - type: object
            description: Definition of pricing tiers.
        measurementUnit:
          allOf:
          - $ref: '#/components/schemas/measurementUnit'
          - type: object
            description: 'Measurement unit and quantity for which the price is defined.


              For example, if a product is sold by the piece, the field should contain `1 pc`. If products relevant to this price model are sold per kilogram, this field should contain `1 kg`.

              '
      required:
      - includesTax
      - name
      - tierDefinition
      - measurementUnit
  parameters:
    trait_priceModel_includesMarkup:
      name: includesMarkup
      in: query
      required: false
      schema:
        type: boolean
      description: 'Flag indicating whether prices assigned to the price model include markup.


        **The `includesMarkup` field is in preview mode** - some of the features may not be fully operational yet.

        '
    trait_priceModel_unitcode:
      name: unitcode
      in: query
      required: false
      schema:
        type: string
      description: Filter price models by unit code
    trait_priceModel_name:
      name: name
      in: query
      required: false
      schema:
        type: string
      description: Price model's name.
    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
    trait_contentLanguage_header:
      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, the localized fields should be provided as strings.

        * If the `Content-Language` header is empty, 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.

        '
    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
    trait_priceModel_tierType:
      name: tierType
      in: query
      required: false
      schema:
        type: string
      description: 'Pricing strategy applicable to the price model. Possible values:

        * `BASIC`

        * `VOLUME`

        * `TIERED`

        '
    trait_priceModel_includesTax:
      name: includesTax
      in: query
      required: false
      schema:
        type: boolean
      description: 'Flag indicating whether prices assigned to the price model are expressed as net or gross.


        | Value | Description |

        | --- | --- |

        | `true` | Prices are expressed as gross values. |

        | `false` | Prices are expressed as net values. |

        '
    trait_acceptLanguage_header:
      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 strings.

        * 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 in the default language defined in the Configuration Service.

        '
    trait_paged_pageSize:
      name: pageSize
      in: query
      description: 'Number of items to be retrieved per page.

        '
      schema:
        default: 60
        minimum: 1
        type: integer
    trait_priceModel_description:
      name: description
      in: query
      required: false
      schema:
        type: string
      description: Price model's description.
    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_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
  responses:
    BadRequest_400:
      description: 'Request was syntactically incorrect. Details are provided in the response payload.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequest400_AmbiguousTenant'
    NotFound_404:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFound404_PriceNotFound'
    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.
  examples:
    BadRequest400_AmbiguousTenant:
      value:
        code: 400
        status: Bad Request
        message: Tenant in the header is not matching with the one provided in the URI.
    NotFound404_PriceNotFound:
      value:
        code: 404
        status: Not Found
        message: 'No custom attribute were found with this key : RandomCustomAttribute'
  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