Newstore tax-transactions API

openapi: 3.2.0
info:
  version: '1.0'
  title: NewStore Tax Transactions 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: tax-transactions
  description: Tax transactions
paths:
  /taxes/previews/transactions:
    post:
      description: Creates a preview tax transaction by calculating the total amounts of cart items using the configured tax strategy, without storing the transaction. Intended to be used for testing and validation purposes.
      summary: createTaxTransactionPreview
      tags:
      - tax-transactions
      operationId: createTaxTransactionPreview
      deprecated: false
      parameters:
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      - name: store-id
        in: header
        required: false
        description: Store identifier.
        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: Tax transaction.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/EnrichedTransactionDto'
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichedTransactionDto'
        '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:
        - taxes:preview-transactions:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionDto'
        required: true
  /taxes/transactions/{orderId}:
    get:
      description: Get tax transaction for the given order identifier.
      summary: showOrderTaxTransaction
      tags:
      - tax-transactions
      operationId: showOrderTaxTransaction
      deprecated: false
      parameters:
      - name: orderId
        in: path
        required: true
        description: Order identifier.
        schema:
          type: string
      - name: store-id
        in: header
        required: false
        description: Store identifier.
        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: Tax transaction.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/EnrichedTransactionDto'
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichedTransactionDto'
        '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 transaction 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:
        - taxes:transactions:read
    patch:
      description: Update tax transaction for the given order identifier.
      summary: updateOrderTaxTransaction
      tags:
      - tax-transactions
      operationId: updateOrderTaxTransaction
      deprecated: false
      parameters:
      - name: orderId
        in: path
        required: true
        description: Order identifier.
        schema:
          type: string
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      - name: store-id
        in: header
        required: false
        description: Store identifier.
        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: Tax transaction.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/EnrichedTransactionDto'
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichedTransactionDto'
        '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 transaction 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:
        - taxes:transactions:read
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionUpdateDto'
        required: true
  /taxes/transactions/{orderId}/returns/{returnId}:
    get:
      description: Get tax transaction for the given return and order identifiers.
      summary: showReturnTaxTransaction
      tags:
      - tax-transactions
      operationId: showReturnTaxTransaction
      deprecated: false
      parameters:
      - name: orderId
        in: path
        required: true
        description: Order identifier.
        schema:
          type: string
      - name: returnId
        in: path
        required: true
        description: Return identifier.
        schema:
          type: string
      - name: store-id
        in: header
        required: false
        description: Store identifier.
        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: Tax transaction.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/EnrichedTransactionDto'
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichedTransactionDto'
        '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 transaction 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:
        - taxes:transactions:read
components:
  schemas:
    EnrichedTransactionAddressDto:
      title: EnrichedTransactionAddressDto
      type: object
      properties:
        address_line_1:
          description: Location address line 1.
          example: 81 Elk Rd Little
          type: string
        address_line_2:
          description: Location address line 2.
          type: string
        city:
          description: Location city.
          example: Albany
          type: string
        country_code:
          type: string
        province:
          description: Location province.
          example: New York
          type: string
        state:
          description: Location state.
          example: New York
          type: string
        store_id:
          description: NewStore Store ID of the address.
          example: Munich-store
          type: string
        zip_code:
          description: Location ZIP code.
          example: '12207'
          type: string
          maxLength: 32
    FallbackErrorDto:
      title: FallbackErrorDto
      type: object
      properties:
        error_code:
          $ref: '#/components/schemas/TaxServiceErrorCode'
        message:
          description: The error message of the underlying tax provider.
          example: Avalara request returned an incomplete or invalid address error
          type: string
        original_tax_provider:
          $ref: '#/components/schemas/TaxCalculationStrategy'
      required:
      - error_code
      - message
      - original_tax_provider
    TransactionType:
      title: TransactionType
      description: Type of the transaction.
      example: SALE
      type: string
      enum:
      - SALE
      - RETURN
    EnrichedTransactionDto:
      title: EnrichedTransactionDto
      type: object
      properties:
        calculation_mode:
          $ref: '#/components/schemas/CalculationMode'
        document_id:
          description: The documentId of the created tax transaction.
          example: '123'
          type: string
        exemption_class:
          $ref: '#/components/schemas/ExemptionClass'
        exemption_number:
          description: 'The number of the customer''s exemption certificate.

            * The given value can be verified by the auditors in the event of a tax audit.'
          type: string
        fallback_error:
          type: object
          allOf:
          - $ref: '#/components/schemas/FallbackErrorDto'
          - description: The optional error of the original tax provider execution that triggered the execution of the fall-back tax provider. Will be returned when the orignal tax provider failure occurs.
        items:
          description: A list of the items sold/returned in the transaction, enriched with the tax amounts.
          type: array
          items:
            $ref: '#/components/schemas/EnrichedTransactionItemDto'
        order_id:
          description: 'The order ID that will be used as a reference to link the order to the created tax transaction in the tax provider records.

            * In case the order ID is not provided then a randomly generated identifier will be used instead.

            * The tax transaction will be stored by using the given value.'
          example: 56bb9975-f43a-4eee-8fb2-200957eb0624
          type: string
        return_id:
          description: 'The return ID that will be used as a reference to link the order to the created tax transaction in the tax provider records.

            * The tax transaction for returns will be stored by using the given value.

            * If the value is not set, the return transaction will not be stored.'
          example: 4fbcc8b3-8511-4ad1-8c9f-96b7c08db664
          type: string
        tax_exempt:
          description: Defines the tax exemption status of the transaction.
          type: boolean
          default: false
        totals:
          type: object
          allOf:
          - $ref: '#/components/schemas/TaxTotalsDto'
          - description: The transaction total amounts.
        transaction_type:
          $ref: '#/components/schemas/TransactionType'
      required:
      - document_id
      - items
      - totals
    TaxServiceErrorCode:
      title: TaxServiceErrorCode
      description: The error code from the underlying tax provider.
      example: taxes_address_validation_failed
      type: string
      enum:
      - taxes_unexpected_error
      - taxes_tenant_missing
      - taxes_config_already_exists
      - taxes_config_not_found
      - taxes_provider_config_missing
      - taxes_tenant_config_required
      - taxes_rounding_failed
      - taxes_invalid_minor_units
      - taxes_unsupported_currency
      - taxes_xml_parsing_failed
      - taxes_provider_error_response
      - taxes_provider_unexpected_response
      - taxes_provider_client_error_response
      - taxes_provider_invalid_credentials
      - taxes_address_validation_failed
      - taxes_provider_config_validation_failed
      - taxes_provider_generic_error
      - taxes_provider_invalid_response
      - taxes_transaction_not_found
      - taxes_commit_integration_error
      - reverse_calculation_provider_error
      - transaction_modification_not_allowed
    TaxTotalsDto:
      title: TaxTotalsDto
      type: object
      properties:
        discount_total:
          description: The total discount amount.
          example: 5
          type: number
          format: double
        grand_total:
          description: The amount consumer has to pay for the order.
          example: 200
          type: number
          format: double
        net_total:
          description: The sum of net prices of all the items including shipping and gift wrapping
          example: 180
          type: number
          format: double
        shipping_tax_amount:
          description: The shipping tax amount.
          example: 5
          type: number
          format: double
        shipping_total:
          description: The total shipping amount.
          example: 5
          type: number
          format: double
        subtotal:
          description: The sum of item prices incl. or excl. tax (depending on tax method).
          example: 180
          type: number
          format: double
        tax_rates_summary:
          description: Summary of the tax rates applied on the line items of the transaction grouped by the tax name and tax rate.
          type: array
          items:
            $ref: '#/components/schemas/TaxRateDto'
        tax_strategy:
          $ref: '#/components/schemas/TaxCalculationStrategy'
        tax_total:
          description: The total tax sum (grand total tax incl. shipping tax).
          example: 20
          type: number
          format: double
      required:
      - discount_total
      - grand_total
      - net_total
      - shipping_tax_amount
      - shipping_total
      - subtotal
      - tax_rates_summary
      - tax_strategy
      - tax_total
    Problem:
      title: Problem
      type: object
      properties:
        detail:
          description: A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: some description for the error situation
          type: string
        error_code:
          type: string
        instance:
          description: A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.
          example: /some/uri-reference#specific-occurrence-context
          type: string
        message:
          type: string
        messages:
          type: array
          items:
            type: string
        request_id:
          type: string
        status:
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          type: integer
          minimum: 100.0
          format: int32
          exclusiveMaximum: 600.0
        title:
          description: A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: some title for the error situation
          type: string
        type:
          description: A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferenceable and point to a human-readable documentation nor globally unique for the problem type.
          example: /some/uri-reference
          type: string
          default: about:blank
    TaxStatus:
      title: TaxStatus
      description: "Type of the tax status applied to the tax line\n\n    * `TAXABLE`: Taxes are applied to the tax line.\n\n* `NOT_TAXABLE`: No taxes are applied to the tax line.\n\n* `EXEMPT`: Taxes are exempt for the tax line."
      example: EXEMPT
      type: string
      enum:
      - EXEMPT
      - TAXABLE
      - NOT_TAXABLE
    ItemType:
      title: ItemType
      description: Type of the item.
      example: product
      type: string
      enum:
      - gift-card
      - gift-wrapping
      - product
      - shipping
    AddItemExtendedAttribute:
      title: AddItemExtendedAttribute
      type: object
      properties:
        name:
          example: engraving
          type: string
        value:
          example: For you.
          type: string
      required:
      - name
      - value
    TaxCalculationStrategy:
      title: TaxCalculationStrategy
      description: Tax calculation strategy.
      example: fixedrate
      type: string
      enum:
      - fixedrate
      - fixed_rate_per_country
      - avalara
      - vertex
      - custom
    SalesOrderTaxMethod:
      title: SalesOrderTaxMethod
      description: Method of calculation of the taxes, can be vat_included or vat_excluded.
      example: vat_excluded
      type: string
      enum:
      - vat_included
      - vat_excluded
    EnrichedTransactionItemDto:
      title: EnrichedTransactionItemDto
      type: object
      properties:
        consumer_uuid:
          description: UUID of the consumer.
          type: string
        currency_consumer:
          description: Currency code shown and billed to the consumer.
          example: USD
          type: string
        extended_attributes:
          description: The item's list of extended attributes.
          type: array
          items:
            $ref: '#/components/schemas/AddItemExtendedAttribute'
        handling_charges:
          description: Cost of handling.
          example: 10
          type: number
          format: double
        id:
          description: Unique identifier of the item.
          example: '123'
          type: string
        item_price:
          description: Price per quantity 1 of the item, can be incl. or excl. tax depending on tax_method.
          example: 200
          type: number
          format: double
        price_line_item:
          description: Gross price for the total quantity of the line item, after all discounts.
          example: 200
          type: number
          format: double
        price_net:
          description: Net price for total quantity of line item, after applying all discounts.
          example: 180
          type: number
          format: double
        price_tax:
          description: Total amount of tax added to the net price, after appplying all discounts.
          example: 20
          type: number
          format: double
        product_id:
          description: Unique identifier of the product.
          example: '123'
          type: string
        product_name:
          description: Human-readable name of the product.
          example: Metallica shirt
          type: string
          maxLength: 512
        product_sku:
          description: SKU of the product.
          example: AIk-0790
          type: string
          maxLength: 256
        quantity:
          description: Item quantity. Positive number for sold items and negative number for returned items
          example: 1
          type: integer
          format: int32
        shipping_address:
          type: object
          allOf:
          - $ref: '#/components/schemas/EnrichedTransactionAddressDto'
          - description: Consumer's shipping address.
        shipping_origin:
          type: object
          allOf:
          - $ref: '#/components/schemas/EnrichedTransactionAddressDto'
          - description: The origin of goods address, e.g. physical address of a store.
        tax_class:
          description: Tax classification identifier for the line item.
          example: AAA000
          type: string
          maxLength: 256
        tax_method:
          $ref: '#/components/schemas/SalesOrderTaxMethod'
        tax_rates:
          description: All applied tax percent values and tax amounts for total quantity of line item (usually more than one rate per line item).
          type: array
          items:
            $ref: '#/components/schemas/TaxRateDto'
        type:
          $ref: '#/components/schemas/ItemType'
      required:
      - item_price
      - price_line_item
      - price_net
      - price_tax
      - quantity
      - shipping_address
      - shipping_origin
      - tax_class
      - tax_method
      - tax_rates
      - type
    TransactionDto:
      title: TransactionDto
      type: object
      properties:
        calculation_mode:
          $ref: '#/components/schemas/CalculationMode'
        exemption_class:
          $ref: '#/components/schemas/ExemptionClass'
        exemption_number:
          description: 'The number of the customer''s exemption certificate.

            * The given value can be verified by the auditors in the event of a tax audit.'
          type: string
        items:
          description: 'A list of the items sold/returned in the transaction.

            * The type `ReverseCalculationTransactionItemDto` should be used when the `calculation_mode` is set to `REVERSE`.

            * The type `TransactionItemDto` should be used When the `calculation_mode` is not sent or set to `STANDARD`.'
          type: array
          items: {}
        order_id:
          description: 'The order ID that will be used as a reference to link the order to the created tax transaction in the tax provider records.

            * In case the order ID is not provided then a randomly generated identifier will be used instead.

            * The tax transaction will be stored by using the given value.'
          example: 56bb9975-f43a-4eee-8fb2-200957eb0624
          type: string
        return_id:
          description: 'The return ID that will be used as a reference to link the order to the created tax transaction in the tax provider records.

            * The tax transaction for returns will be stored by using the given value.

            * If the value is not set, the return transaction will not be stored.'
          example: 4fbcc8b3-8511-4ad1-8c9f-96b7c08db664
          type: string
        tax_date:
          description: Date of the transaction (in UTC timezone) that'll be used in committing taxes.
          example: '2023-09-25T01:23:45Z'
          type: string
          format: date-time
        tax_exempt:
          description: Defines the tax exemption status of the transaction.
          type: boolean
          default: false
        transaction_type:
          $ref: '#/components/schemas/TransactionType'
      required:
      - items
      - order_id
    CalculationMode:
      title: CalculationMode
      description: 'Type of the tax calculation


        * `STANDARD`: Standard tax calculation (default).

        * Taxes will be calculated for each line from `item_price * quantity` respecting the `tax_method` (tax incl./excl.).



        * `REVERSE`: Reverse calculation of taxes from the total amount paid by customer (e.g. for injected offline or e-comm orders).

        * Taxes will be calculated from `price_line_item` (total gross amount for given quantity) regardless of `tax_method` (tax incl./excl.).'
      example: STANDARD
      type: string
      enum:
      - STANDARD
      - REVERSE
    TaxRateDto:
      title: TaxRateDto
      type: object
      properties:
        amount:
          description: Monetary tax amount for the unit price corresponding to this tax_rate item's percent value, e.g. 3.37.
          example: 10
          type: number
          format: double
        country_code:
          description: Country of jurisdiction for the applied tax.
          example: US
          type: string
        exempt_amount:
 

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