Newstore store-tax-configuration API

openapi: 3.2.0
info:
  version: '1.0'
  title: NewStore Store Tax Configuration API
  description: NewStore public APIs
  contact:
    email: support@newstore.com
    name: NewStore API Support
    url: https://developer.newstore.com
servers:
- url: https://dodici-demo.p.newstore.net/
security: []
tags:
- name: store-tax-configuration
  description: Tax configuration - Store
paths:
  /taxes/config/stores:
    get:
      description: List store tax calculation configurations with the given query.
      summary: listStoreConfigs
      tags:
      - store-tax-configuration
      operationId: listStoreConfigs
      deprecated: false
      parameters:
      - name: limit
        in: query
        required: true
        description: Limit number of results to this value.
        schema:
          type: integer
          format: int32
          maximum: 100.0
          minimum: 1.0
      - name: tax_calculation_strategy
        in: query
        required: false
        description: Tax calculation strategy to filter by.
        schema:
          type: string
          enum:
          - fixedrate
          - fixed_rate_per_country
          - avalara
          - vertex
          - custom
      - name: next_page_key
        in: query
        required: false
        description: Key to be used to get the next page of results.
        schema:
          type: string
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: List of tax configurations of stores.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/StoreConfigListDto'
            application/json:
              schema:
                $ref: '#/components/schemas/StoreConfigListDto'
        '400':
          description: Bad request.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:read
    post:
      description: Create a tax calculation configuration for the specified store identifier.
      summary: createStoreConfig
      tags:
      - store-tax-configuration
      operationId: createStoreConfig
      deprecated: false
      parameters:
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '201':
          description: Tax configuration of the store.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/StoreConfigDto'
            application/json:
              schema:
                $ref: '#/components/schemas/StoreConfigDto'
        '400':
          description: Bad request.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Tax configuration for the given store was already created.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreConfigCreateDto'
        required: true
  /taxes/config/stores/{id}:
    delete:
      description: Delete tax configuration for the given store identifier.
      summary: destroyStoreConfig
      tags:
      - store-tax-configuration
      operationId: destroyStoreConfig
      deprecated: false
      parameters:
      - name: id
        in: path
        required: true
        description: Store identifier.
        schema:
          type: string
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '204':
          description: Tax configuration deleted for the given store identifier.
          headers: {}
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Tax configuration not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:write
    get:
      description: Get tax configuration for the given store identifier.
      summary: showStoreConfig
      tags:
      - store-tax-configuration
      operationId: showStoreConfig
      deprecated: false
      parameters:
      - name: id
        in: path
        required: true
        description: Store identifier.
        schema:
          type: string
      - name: version
        in: query
        required: false
        description: Specific configuration version number to fetch. If left empty, the latest version of the configuration will be returned.
        schema:
          type: integer
          format: int32
          minimum: 0.0
      - name: merged_tenant_fallback
        in: query
        required: false
        description: Flag that indicates if the store configuration should be merged with the tenant configuration to provide tenant level fallbacks to the store. This flag defaults to true if it is not sent.
        schema:
          type: boolean
          default: true
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: 'Tax configuration of the store.

            * If the `merged_tenant_fallback` is set to `false`, the response will contain a store configuration `StoreConfigDto`.

            * If the `merged_tenant_fallback` is set to `true` or not sent, the response will contain a merged store configuration and tenant configuration `ConfigDto`.'
          headers: {}
          content:
            application/problem+json:
              schema: {}
            application/json:
              schema: {}
        '400':
          description: Bad request.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Tax configuration not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:read
    patch:
      description: Partially update the tax configuration of a store by merging the given fields with the existing fields.
      summary: updateStoreConfig
      tags:
      - store-tax-configuration
      operationId: updateStoreConfig
      deprecated: false
      parameters:
      - name: id
        in: path
        required: true
        description: Store identifier.
        schema:
          type: string
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: Tax configuration of the store.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/StoreConfigDto'
            application/json:
              schema:
                $ref: '#/components/schemas/StoreConfigDto'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Tax configuration not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreConfigUpdateDto'
        required: true
components:
  schemas:
    VertexExemptionClassItemUpdateDto:
      title: VertexExemptionClassItemUpdateDto
      type: object
      properties:
        display_text:
          description: 'Display text to be used in Associate App while rendering the exemption class.

            * Required for custom tax exemption classes.

            * Optional for pre-defined tax exemption classes.

            * Keys must be a valid ISO 639-1 language code.

            * Must include English translation by default.'
          example:
            en: First Nation Citizen
            fr: Premières Nations
          type: object
          additionalProperties: {}
        exemption_class:
          $ref: '#/components/schemas/ExemptionClass'
        valid_countries:
          description: The list of countries where this tax exemption class is valid.
          type: array
          items:
            $ref: '#/components/schemas/TaxExemptionCountryCode'
        vertex_class_code:
          description: 'Vertex class code.

            * A code used to represent groups of customers, vendors, dispatchers, or recipients who have similar taxability.'
          example: '01'
          type: string
          minLength: 1
          maxLength: 20
      required:
      - exemption_class
      - valid_countries
      - vertex_class_code
    FixedRateConfigUpdateDto:
      title: FixedRateConfigUpdateDto
      type: object
      properties:
        exemption_classes:
          description: A list of supported exemption classes.
          type: array
          items:
            $ref: '#/components/schemas/ExemptionClassItemUpdateDto'
        tax_name:
          description: Tax name to be used in the tax lines.
          example: Standard VAT rate
          type: string
        tax_rate:
          description: 'Tax rate to be used as a fixed rate during tax calculations.

            * Allows up to 5 decimal points.'
          example: 0.19
          type: number
          format: double
    VertexExemptionClassItemDto:
      title: VertexExemptionClassItemDto
      type: object
      properties:
        display_text:
          description: 'Display text to be used in Associate App while rendering the exemption class.

            * Required for custom tax exemption classes.

            * Optional for pre-defined tax exemption classes.

            * Keys must be a valid ISO 639-1 language code.

            * Must include English translation by default.'
          example:
            en: First Nation Citizen
            fr: Premières Nations
          type: object
          additionalProperties: {}
        exemption_class:
          $ref: '#/components/schemas/ExemptionClass'
        valid_countries:
          description: The list of countries where this tax exemption class is valid.
          type: array
          items:
            $ref: '#/components/schemas/TaxExemptionCountryCode'
        vertex_class_code:
          description: 'Vertex class code.

            * A code used to represent groups of customers, vendors, dispatchers, or recipients who have similar taxability.'
          example: '01'
          type: string
          minLength: 1
          maxLength: 20
      required:
      - exemption_class
      - valid_countries
      - vertex_class_code
    VertexAuthLoginType:
      title: VertexAuthLoginType
      description: 'Vertex Login Type.

        * Used for selecting the authentication method.

        * `trusted_id` field is required if `login_type` is set to `trusted_id`.

        * `username` and `password` fields are required if `login_type` is set to `user_and_password`.'
      example: trusted_id
      type: string
      enum:
      - trusted_id
      - user_and_password
    FixedRateConfigDto:
      title: FixedRateConfigDto
      type: object
      properties:
        exemption_classes:
          description: A list of supported exemption classes.
          type: array
          items:
            $ref: '#/components/schemas/ExemptionClassItemDto'
        tax_name:
          description: Tax name to be used in the tax lines.
          example: Standard VAT rate
          type: string
        tax_rate:
          description: 'Tax rate to be used as a fixed rate during tax calculations.

            * Allows up to 5 decimal points.'
          example: 0.19
          type: number
          format: double
      required:
      - tax_rate
    VertexAdministrativeOriginDto:
      title: VertexAdministrativeOriginDto
      type: object
      properties:
        city:
          description: The proper name of the city used to determine the Tax Area ID.
          example: Berlin
          type: string
          minLength: 1
          maxLength: 60
        country:
          type: string
        currency_code:
          $ref: '#/components/schemas/Currency3'
        currency_value:
          description: The rate (multiplier) used for converting the transaction currency amount to the filing currency amount.
          example: 1.1
          type: number
          format: double
        main_division:
          description: The proper name or the postal abbreviation of the state, province, or territory used to determine the Tax Area ID.
          example: Berlin
          type: string
          minLength: 1
          maxLength: 60
        postal_code:
          description: The postal code used to determine the Tax Area ID
          example: '10785'
          type: string
          minLength: 1
          maxLength: 20
        street_address_1:
          description: The first line of the street address.
          example: Potsdamer Str. 7
          type: string
          minLength: 1
          maxLength: 100
        street_address_2:
          description: The second line of the street address.
          example: Potsdamer Platz
          type: string
          minLength: 1
          maxLength: 100
      required:
      - city
      - country
      - currency_code
      - currency_value
      - main_division
      - postal_code
      - street_address_1
      - street_address_2
    StoreConfigCreateDto:
      title: StoreConfigCreateDto
      type: object
      properties:
        avalara:
          type: object
          allOf:
          - $ref: '#/components/schemas/AvalaraConfigCreateDto'
          - description: 'Avalara configuration.

              * Required if the `tax_calculation_strategy` is set to `avalara`.

              * If the tax calculation strategy is set to `avalara`, the given configuration will be used.

              * If the Avalara configuration is defined, the configuration will be validated through a ping request to Avalara, which will validate the authenticity of Avalara credentials.'
            example:
              account_number: '2000123456'
              company_code: NEWSTOREINC
              default_customer_code: Anonymous customer
              environment: sandbox
              license_key: C1234567890ABCFE
        country_code:
          type: string
        custom:
          type: object
          allOf:
          - $ref: '#/components/schemas/CustomConfigCreateDto'
          - description: 'Custom provider configuration.

              * Required if the `tax_calculation_strategy` is set to `custom`.

              * If the tax calculation strategy is set to `custom`, the given configuration will be used.'
            example:
              api_version: v1
              base_url: https://my-custom-tax-url.com
        fixed_rate:
          type: object
          allOf:
          - $ref: '#/components/schemas/FixedRateConfigCreateDto'
          - description: 'Fixed rate configuration.

              * If the tax calculation strategy is set to `fixedrate`, the specified tax rate will be used.

              * For the other tax calculation strategies, the specified rate will be used as a fallback if the tax calculation fails (e.g. if the tax provider is not reachable).

              * The specified rate will be used as a fallback by the Associate App in offline-mode.'
            example:
              tax_name: Standard VAT rate for Austria
              tax_rate: 0.2
        fixed_rate_per_country:
          description: "Fixed rate configuration per country.\n* Uses ISO 3166 Alpha-2 format as the key in upper-case.\n* Fixed rate specification can be defined under each country key for the desired countries.\n* If the tax calculation strategy is set to `fixed_rate_per_country`:\n\n\n  * Fixed rate configuration must be configured.\n  * The specified tax rate will be used if the country code of the store has a fixed rate configuration.\n  * The tax calculation will fail if the country code of the store does not have a fixed rate configuration."
          example:
            AT:
              tax_name: Standard VAT rate for Austria
              tax_rate: 0.2
            DE:
              tax_name: Standard VAT rate for Germany
              tax_rate: 0.19
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FixedRateConfigCreateDto'
        store_id:
          description: Store identifier within the NewStore platform.
          example: '123'
          type: string
        tax_calculation_strategy:
          $ref: '#/components/schemas/TaxCalculationStrategy'
        vertex:
          type: object
          allOf:
          - $ref: '#/components/schemas/VertexConfigCreateDto'
          - description: 'Vertex configuration.

              * Required if the `tax_calculation_strategy` is set to `vertex`.

              * If the tax calculation strategy is set to `vertex`, the given configuration will be used.

              * If the Vertex configuration is defined, the configuration will be validated through a ping request to Vertex, which will validate the authenticity of Vertex credentials.'
            example:
              administrative_origin:
                city: Berlin
                country: DE
                currency_code: EUR
                currency_value: 1.1
                main_division: Berlin
                postal_code: '10785'
                street_address_1: Potsdamer Str. 7
                street_address_2: Potsdamer Platz
              company_code: '1234'
              division_code: '1234'
              flexible_fields:
              - extended_attribute_name: productClass
                target_field_id: 1
                target_field_type: flexible_code_field
              - extended_attribute_name: shoeSize
                target_field_id: 1
                target_field_type: flexible_numeric_field
              login_type: trusted_id
              soap_url: https://sandboxap2.na1.ondemand.vertexinc.com/vertex-ws/services/CalculateTax90
              trusted_id: 9SDPdc9bo3
      required:
      - country_code
      - store_id
    AvalaraExemptionClassItemDto:
      title: AvalaraExemptionClassItemDto
      type: object
      properties:
        avalara_entity_use_code:
          description: 'Avalara entity use code.

            * For pre-defined tax exemption classes, value must correspond to the Avalara entity use code. For the possible options, please refer to the [List of entity use codes](https://knowledge.avalara.com/bundle/hff1682048150115_hff1682048150115/page/List_of_entity_use_codes.html).

            * For custom tax exemption classes, value must correspond to the custom entity use code defined under the exempt entity custom tax rule.'
          example: CANADA_FNC
          type: string
          minLength: 1
          maxLength: 25
        display_text:
          description: 'Display text to be used in Associate App while rendering the exemption class.

            * Required for custom tax exemption classes.

            * Optional for pre-defined tax exemption classes.

            * Keys must be a valid ISO 639-1 language code.

            * Must include English translation by default.'
          example:
            en: First Nation Citizen
            fr: Premières Nations
          type: object
          additionalProperties: {}
        exemption_class:
          $ref: '#/components/schemas/ExemptionClass'
        valid_countries:
          description: The list of countries where this tax exemption class is valid.
          type: array
          items:
            $ref: '#/components/schemas/TaxExemptionCountryCode'
      required:
      - avalara_entity_use_code
      - exemption_class
      - valid_countries
    CustomConfigAdditionalUpdateDto:
      title: CustomConfigAdditionalUpdateDto
      type: object
      properties:
        avalara:
          type: object
          allOf:
          - $ref: '#/components/schemas/CustomV0AvalaraConfigUpdateDto'
          - description: 'Avalara custom provider configuration.

              * Required if the `api_version` is set to `v0-avalara`.

              * If the tax calculation strategy is set to `custom` and `api_version` is set to `v0-avalara`, the given configuration will be used.'
            example:
              account_number: '2000123456'
              company_code: NEWSTOREINC
              license_key: C1234567890ABCFE
              url: https://custom.provider.net/1.0/tax/get
    CustomConfigCreateDto:
      title: CustomConfigCreateDto
      type: object
      properties:
        additional_config:
          type: object
          allOf:
          - $ref: '#/components/schemas/CustomConfigAdditionalCreateDto'
          - description: Other necessary configuration specific to the custom provider (currently configs for non-officially supported avalara based custom implementation)
        api_version:
          $ref: '#/components/schema

# --- truncated at 32 KB (93 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newstore/refs/heads/main/openapi/newstore-store-tax-configuration-api-openapi.yml