OpenAPI Specification
swagger: '2.0'
info:
version: '1.0'
title: NewStore address tax-transactions API
description: NewStore public APIs
contact:
email: support@newstore.com
name: NewStore API Support
url: https://developer.newstore.com
host: dodici-demo.p.newstore.net
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json
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
produces:
- application/problem+json
- application/json
consumes:
- application/json
parameters:
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
$ref: '#/definitions/TransactionDto'
- name: store-id
in: header
required: false
type: string
description: Store identifier.
responses:
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'200':
description: Tax transaction.
schema:
$ref: '#/definitions/EnrichedTransactionDto'
headers: {}
'400':
description: Bad request.
schema:
$ref: '#/definitions/Problem'
headers: {}
'401':
description: Unauthorized.
schema:
$ref: '#/definitions/Problem'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- taxes:preview-transactions:write
/taxes/transactions/{orderId}:
get:
description: Get tax transaction for the given order identifier.
summary: showOrderTaxTransaction
tags:
- tax-transactions
operationId: showOrderTaxTransaction
deprecated: false
produces:
- application/problem+json
- application/json
parameters:
- name: orderId
in: path
required: true
type: string
description: Order identifier.
- name: store-id
in: header
required: false
type: string
description: Store identifier.
responses:
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'200':
description: Tax transaction.
schema:
$ref: '#/definitions/EnrichedTransactionDto'
headers: {}
'401':
description: Unauthorized.
schema:
$ref: '#/definitions/Problem'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Tax transaction not found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- taxes:transactions:read
patch:
description: Update tax transaction for the given order identifier.
summary: updateOrderTaxTransaction
tags:
- tax-transactions
operationId: updateOrderTaxTransaction
deprecated: false
produces:
- application/problem+json
- application/json
consumes:
- application/json
parameters:
- name: orderId
in: path
required: true
type: string
description: Order identifier.
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
$ref: '#/definitions/TransactionUpdateDto'
- name: store-id
in: header
required: false
type: string
description: Store identifier.
responses:
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'200':
description: Tax transaction.
schema:
$ref: '#/definitions/EnrichedTransactionDto'
headers: {}
'400':
description: Bad request.
schema:
$ref: '#/definitions/Problem'
headers: {}
'401':
description: Unauthorized.
schema:
$ref: '#/definitions/Problem'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Tax transaction not found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- taxes:transactions:read
/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
produces:
- application/problem+json
- application/json
parameters:
- name: orderId
in: path
required: true
type: string
description: Order identifier.
- name: returnId
in: path
required: true
type: string
description: Return identifier.
- name: store-id
in: header
required: false
type: string
description: Store identifier.
responses:
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'200':
description: Tax transaction.
schema:
$ref: '#/definitions/EnrichedTransactionDto'
headers: {}
'401':
description: Unauthorized.
schema:
$ref: '#/definitions/Problem'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Tax transaction not found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- taxes:transactions:read
definitions:
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:
description: The item net amount which has been tax exempt.
example: 10
type: number
format: double
rate:
description: Tax percent value for this tax rate item, e.g. 0.19 means 19% tax.
example: 0.19
type: number
format: double
tax_name:
description: Name of the applied tax.
example: Colorado retail delivery fee
type: string
tax_status:
$ref: '#/definitions/TaxStatus'
taxable_amount:
description: The taxable item net amount on which the tax is chargeable.
example: 10
type: number
format: double
required:
- amount
- country_code
- rate
- tax_name
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
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
maximum: 600.0
exclusiveMaximum: true
format: int32
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
AddItemExtendedAttribute:
title: AddItemExtendedAttribute
type: object
properties:
name:
example: engraving
type: string
value:
example: For you.
type: string
required:
- name
- value
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
EnrichedTransactionDto:
title: EnrichedTransactionDto
type: object
properties:
calculation_mode:
$ref: '#/definitions/CalculationMode'
document_id:
description: The documentId of the created tax transaction.
example: '123'
type: string
exemption_class:
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/TaxTotalsDto'
- description: The transaction total amounts.
transaction_type:
$ref: '#/definitions/TransactionType'
required:
- document_id
- items
- totals
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
ExemptionClass:
title: ExemptionClass
description: 'The tax exemption class that identifies the customer''s group/organization that accredited them with the tax exemption status.
* For custom tax exemption classes, the `CUSTOM_` prefix with a UPPER_SNAKE_CASE key can be used. Example: `CUSTOM_CANADA`'
example: CHARITY_ORGANIZATION
type: string
enum:
- FEDERAL_GOVERNMENT
- STATE_GOVERNMENT
- TRIBAL_GOVERNMENT
- LOCAL_GOVERNMENT
- FOREIGN_DIPLOMAT
- CHARITY_ORGANIZATION
- RELIGIOUS_ORGANIZATION
- EDUCATIONAL_ORGANIZATION
- RESALE
- DIRECT_PAY_PERMIT
- OTHER
- NON_RESIDENT
- FIRST_NATION_CITIZEN
- CUSTOM_*
TransactionUpdateDto:
title: TransactionUpdateDto
type: object
properties:
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
required:
- order_id
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
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: '#/definitions/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: '#/definitions/EnrichedTransactionAddressDto'
- description: Consumer's shipping address.
shipping_origin:
type: object
allOf:
- $ref: '#/definitions/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: '#/definitions/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: '#/definitions/TaxRateDto'
type:
$ref: '#/definitions/ItemType'
required:
- item_price
- price_line_item
- price_net
- price_tax
- quantity
- shipping_address
- shipping_origin
- tax_class
- tax_method
- tax_rates
- type
FallbackErrorDto:
title: FallbackErrorDto
type: object
properties:
error_code:
$ref: '#/definitions/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: '#/definitions/TaxCalculationStrategy'
required:
- error_code
- message
- original_tax_provider
TaxCalculationStrategy:
title: TaxCalculationStrategy
description: Tax calculation strategy.
example: fixedrate
type: string
enum:
- fixedrate
- fixed_rate_per_country
- avalara
- vertex
- custom
ItemType:
title: ItemType
description: Type of the item.
example: product
type: string
enum:
- gift-card
- gift-wrapping
- product
- shipping
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
TransactionType:
title: TransactionType
description: Type of the transaction.
example: SALE
type: string
enum:
- SALE
- RETURN
TransactionDto:
title: TransactionDto
type: object
properties:
calculation_mode:
$ref: '#/definitions/CalculationMode'
exemption_class:
$ref: '#/definitions/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: '#/definitions/TransactionType'
required:
- items
- order_id
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: '#/definitions/TaxRateDto'
tax_strategy:
$ref: '#/definitions/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
securityDefinitions:
oauth:
type: oauth2
flow: application
tokenUrl: https://id.p.newstore.net/auth/realms/dodici-demo/protocol/openid-connect/token
scopes:
catalog:import-schemas:read: Grants privileges to read import schema
catalog:import-schemas:write: Grants privileges to write import schema
catalog:pricebook-export:read: Grants privileges to export pricebook data
catalog:product-export:read: Grants privileges to export product data
checkout:carts:read: Grants privileges to read cart data
checkout:carts:write: Grants privileges to write cart data
clienteling:profile:read: Grants privileges to read clienteling profiles
customer:profile:read: Grants privileges to read API customer data
customer:profile:write: Grants privileges to modify API customer data
newstore:configuration:read: Grants privileges to read configuration
newstore:configuration:write: Grants privileges to write configuration
fiscalization:orders:read: View orders with fiscal transactions and signatures
fiscalization:orders:write: Create orders with fiscal transactions and signatures
shipments:read: Read Shipping Options and Audits
iam:providers:read: ' Grants read privileges to provider resources'
iam:providers:write: ' Grants write privileges to provider resources'
iam:roles:read: ' Grants privileges to read roles data'
iam:roles:write: ' Grants privileges to write roles data'
iam:users:read: ' Grants privileges to read user data'
iam:users:write: ' Grants privileges to write user data'
inventory:reservations:read: Allows access to retrieve reservations
inventory:reservations:write: Allows access to create and update reservations
promotions:config:read: Grants privileges to read configuration
promotions:config:write: Grants privileges to write into configuration
promotions:reason-codes:read: Grants privileges to list reason codes
promotions:reason-codes:write: Grants privileges to create and update reason codes
audit-events:read: Grants read access to the tenant's audit events.
taxes:preview-transactions:write: Preview tax transactions
taxes:transactions:read: Read tax transactions