# Upsert Transaction ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /v1/transactions/source/{source}/externalId/{externalId}: put: summary: Upsert Transaction deprecated: false description: Update or Insert Transaction by External ID and source operationId: upsertTransactionByExternalId tags: - Endpoints/Transactions - transaction parameters: - name: externalId in: path description: External ID required: true example: '{{transactionExternalId}}' schema: type: string - name: source in: path description: Transaction Source (should be [1-9]) required: true example: '{{source}}' schema: pattern: '[1-9]' type: string requestBody: content: application/json: schema: type: object x-apidog-refs: 01JKXDKA6BXZ6KDQPVQZKDS56K: $ref: '#/components/schemas/transaction%20Request' x-apidog-overrides: shippingAddress: &ref_0 description: The address that the tax calculation based on $ref: '#/components/schemas/shippingAddress%20Copy' required: - shippingAddress x-apidog-orders: - 01JKXDKA6BXZ6KDQPVQZKDS56K properties: externalId: maxLength: 256 minLength: 1 type: string description: >- the attribute designed to receive a unique identifier provided by API consumers themselves (e.g. pass your own ID) source: pattern: ^(10|[1-9])$ type: string description: >- a single digit which identifies your different stores, checkout solutions, marketplaces, etc. defined by the API consumers (to avoid external id duplications) documentName: maxLength: 50 minLength: 0 type: string description: The name of the document, as shown in the ERP systems items: type: array items: &ref_2 $ref: '#/components/schemas/Item%20Request' isTaxInclusive: type: boolean description: >- Indicates whether tax is included in the total items price (true) or added as a separate charge (false). billingAddress: &ref_3 $ref: '#/components/schemas/billingAddress' shippingAddress: *ref_0 customerId: type: string description: >- The Complyt ID of the customer associated with the transaction format: uuid customerExternalId: type: string description: >- The external customer ID to used in addition with customer source to locate a customer instead of using the customerId. If customerID is added, it will be prefererd. customerSource: type: string description: >- The external customer source to used in addition with customer external ID to locate a customer instead of using the customerId. If customerID is added, it will be prefererd. transactionStatus: type: string description: The status of the transaction enum: - ACTIVE - CANCELLED - PAID externalTimestamps: &ref_4 $ref: '#/components/schemas/externalTimestamps' transactionType: type: string description: >- The type of the transaction. Only invoices are considered for nexus tracking and for actual tax calculation enum: - SALES_ORDER - INVOICE - ESTIMATE - REFUND - TAXABLE_REFUND x-apidog-enum: - name: '' value: SALES_ORDER description: '' - name: '' value: INVOICE description: '' - name: '' value: ESTIMATE description: '' - name: '' value: REFUND description: '' - name: '' value: TAXABLE_REFUND description: '' shippingFee: &ref_5 $ref: '#/components/schemas/ShippingFee' createdFrom: maxLength: 256 minLength: 0 type: string description: >- The external ID of the document that preceded this transaction creation (e.g., when creating an invoice, you can pass the ID of the sales order that it originated from here) transactionLevelDiscount: type: number description: The discount to apply on the overall transaction transactionFilingStatus: type: string description: >- Indicates the status of the transaction in relation to its submission to a specific state. Possible values include: - NOT_FILED: The transaction has not been submitted to the state. - FILED: The transaction has been successfully submitted to the state. enum: - NOT_FILED - FILED currency: type: string description: The currency of the transaction. not mandatory refRate: type: number description: The manual currency exchange rate subsidiary: type: string isRefundLinked: type: boolean description: >- If set to true, the sales tax will be taken from the invoice specified in the createdFrom field and returned as the refund's salesTax.amount required: - externalId - source - items - shippingAddress - customerId - transactionStatus - externalTimestamps - transactionType x-apidog-ignore-properties: - externalId - source - documentName - items - isTaxInclusive - billingAddress - shippingAddress - customerId - customerExternalId - customerSource - transactionStatus - externalTimestamps - transactionType - shippingFee - createdFrom - transactionLevelDiscount - transactionFilingStatus - currency - refRate - subsidiary - isRefundLinked example: externalId: '{{transactionExternalId}}' source: '{{source}}' items: - unitPrice: 100 quantity: 1 totalPrice: 100 description: string name: string taxCode: C1S1 manualSalesTax: false manualSalesTaxRate: 0 billingAddress: city: '' country: US county: null state: CA street: 3098 N Remington Ave zip: 93711-5508 region: string isPartial: false shippingAddress: city: fresno country: US county: null state: CA street: 3098 N Remington Ave zip: 93711-5508 region: string isPartial: false customerId: '{{customerComplytId}}' externalTimestamps: createdDate: '2023-02-05T12:24:43.193Z' updatedDate: '2023-02-05T12:24:43.193Z' transactionStatus: ACTIVE transactionType: INVOICE createdFrom: string transactionFilingStatus: NOT_FILED currency: USD responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/transaction%20Response' example: | { "complytId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "externalId": "999444", "source": "1", "items": [ { "unitPrice": 0, "quantity": 0, "totalPrice": 0, "calculatedTotal":0, "discount":0, "description": "string", "name": "string", "taxCode": "string", "jurisdictionalSalesTaxRules": { "name": "string", "abbreviation": "string", "taxable": true, "specialTreatment": true, "calculationType": "FIXED", "description": "string", "calculationValue": 0, "cities": null, "regions":null }, "salesTaxRates": { "cityDistrictRate": 0, "cityRate": 0, "countyDistrictRate": 0, "countyRate": 0, "stateRate": 0, "taxRate": 0 }, "gtRates": { "countryRate": 0, "regionRate": 0, "taxRate": 0 }, "manualSalesTax": true, "manualSalesTaxRate": 0, "tangibleCategory": "TANGIBLE", "taxableCategory": "TAXABLE" } ], "billingAddress": { "city": "string", "country": "string", "county": "string", "state": "string", "street": "string", "zip": "string", "isPartial": false }, "shippingAddress": { "city": "string", "country": "string", "county": "string", "state": "string", "street": "string", "zip": "string", "region":"string", "isPartial": false, "matchedAddressData": { "address": { "city": "string", "country": "string", "county": "string", "state": "string", "zip": "string" }, "scoring": { "matchLevel": "string", "score": 1.0, "fieldScore": { "countryMatch": "string", "stateMatch": "string", "cityMatch": "string", "zipMatch": "string" } } } }, "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customer": { "complytId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "externalId": "string", "source": "7", "name": "string", "address": { "city": "string", "country": "string", "county": "string", "state": "string", "street": "string", "zip": "string", "isPartial": false }, "email": "example@some.mail.com", "customerType": "RETAIL", "internalTimestamps": { "createdDate": "2023-02-05T12:24:43.193Z", "updatedDate": "2023-02-05T12:24:43.193Z" }, "externalTimestamps": { "createdDate": "2023-02-05T12:24:43.193Z", "updatedDate": "2023-02-05T12:24:43.193Z" } }, "salesTax": { "amount": 0, "taxRate": 0, "salesTaxRates": { "cityDistrictRate": 0, "cityRate": 0, "countyDistrictRate": 0, "countyRate": 0, "stateRate": 0, "taxRate": 0 }, "gtRates": { "countryRate": 0, "regionRate": 0, "taxRate": 0 }, }, "transactionStatus": "ACTIVE", "internalTimestamps": { "createdDate": "2023-02-05T12:24:43.193Z", "updatedDate": "2023-02-05T12:24:43.193Z" }, "externalTimestamps": { "createdDate":"2023-02-05T12:24:43.193Z", "updatedDate": "2023-02-05T12:24:43.193Z" }, "transactionType": "SALES_ORDER", "shippingFee": { "manualSalesTax": true, "manualSalesTaxRate": 0, "totalPrice": 0, "calculatedTotal":0, "taxCode": "string", "taxableCategory": "TAXABLE", "tangibleCategory": "TANGIBLE", "jurisdictionalSalesTaxRules": { "name": "string", "abbreviation": "string", "taxable": true, "specialTreatment": true, "calculationType": "FIXED", "description": "string", "calculationValue": 0, "cities": null }, "salesTaxRates": { "cityDistrictRate": 0, "cityRate": 0, "countyDistrictRate": 0, "countyRate": 0, "stateRate": 0, "taxRate": 0 }, "gtRates": { "countryRate": 0, "regionRate": 0, "taxRate": 0 }, }, "createdFrom": "string", "taxableItemsAmount": 0, "tangibleItemsAmount": 0, "totalItemsAmount": 0, "totalDiscount" :0, "transactionFilingStatus": "NOT_FILED" } headers: {} x-apidog-name: Successful operation '201': description: '' content: application/json: schema: $ref: '#/components/schemas/transaction' example: | { "complytId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "externalId": "999444", "source": "1", "items": [ { "unitPrice": 0, "quantity": 0, "totalPrice": 0, "calculatedTotal":0, "discount":0, "description": "string", "name": "string", "taxCode": "string", "jurisdictionalSalesTaxRules": { "name": "string", "abbreviation": "string", "taxable": true, "specialTreatment": true, "calculationType": "FIXED", "description": "string", "calculationValue": 0, "cities": null, "regions":null }, "salesTaxRates": { "cityDistrictRate": 0, "cityRate": 0, "countyDistrictRate": 0, "countyRate": 0, "stateRate": 0, "taxRate": 0 }, "gtRates": { "countryRate": 0, "regionRate": 0, "taxRate": 0 }, "manualSalesTax": true, "manualSalesTaxRate": 0, "tangibleCategory": "TANGIBLE", "taxableCategory": "TAXABLE" } ], "billingAddress": { "city": "string", "country": "string", "county": "string", "state": "string", "street": "string", "zip": "string", "isPartial": false }, "shippingAddress": { "city": "string", "country": "string", "county": "string", "state": "string", "street": "string", "zip": "string", "region":"string", "isPartial": false, "matchedAddressData": { "address": { "city": "string", "country": "string", "county": "string", "state": "string", "zip": "string" }, "scoring": { "matchLevel": "string", "score": 1.0, "fieldScore": { "countryMatch": "string", "stateMatch": "string", "cityMatch": "string", "zipMatch": "string" } } } }, "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customer": { "complytId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "externalId": "string", "source": "7", "name": "string", "address": { "city": "string", "country": "string", "county": "string", "state": "string", "street": "string", "zip": "string", "isPartial": false }, "email": "example@some.mail.com", "customerType": "RETAIL", "internalTimestamps": { "createdDate": "2023-02-05T12:24:43.193Z", "updatedDate": "2023-02-05T12:24:43.193Z" }, "externalTimestamps": { "createdDate": "2023-02-05T12:24:43.193Z", "updatedDate": "2023-02-05T12:24:43.193Z" } }, "salesTax": { "amount": 0, "taxRate": 0, "salesTaxRates": { "cityDistrictRate": 0, "cityRate": 0, "countyDistrictRate": 0, "countyRate": 0, "stateRate": 0, "taxRate": 0 }, "gtRates": { "countryRate": 0, "regionRate": 0, "taxRate": 0 }, }, "transactionStatus": "ACTIVE", "internalTimestamps": { "createdDate": "2023-02-05T12:24:43.193Z", "updatedDate": "2023-02-05T12:24:43.193Z" }, "externalTimestamps": { "createdDate":"2023-02-05T12:24:43.193Z", "updatedDate": "2023-02-05T12:24:43.193Z" }, "transactionType": "SALES_ORDER", "shippingFee": { "manualSalesTax": true, "manualSalesTaxRate": 0, "totalPrice": 0, "calculatedTotal":0, "taxCode": "string", "taxableCategory": "TAXABLE", "tangibleCategory": "TANGIBLE", "jurisdictionalSalesTaxRules": { "name": "string", "abbreviation": "string", "taxable": true, "specialTreatment": true, "calculationType": "FIXED", "description": "string", "calculationValue": 0, "cities": null }, "salesTaxRates": { "cityDistrictRate": 0, "cityRate": 0, "countyDistrictRate": 0, "countyRate": 0, "stateRate": 0, "taxRate": 0 }, "gtRates": { "countryRate": 0, "regionRate": 0, "taxRate": 0 }, }, "createdFrom": "string", "taxableItemsAmount": 0, "tangibleItemsAmount": 0, "totalItemsAmount": 0, "totalDiscount" :0, "transactionFilingStatus": "NOT_FILED" } headers: {} x-apidog-name: Successful operation '400': description: '' content: application/json: schema: type: object properties: code: type: integer requestId: type: string error: type: string message: type: string url: type: string timestamp: type: string required: - code - requestId - error - message - url - timestamp x-apidog-orders: - code - requestId - error - message - url - timestamp x-apidog-ignore-properties: [] examples: '2': summary: Zip Format Invalid value: message: >- Zip format is incorrect. The correct format is mandatory 5 digits and optional dash and and additional 4 digits. example: 12345 or 12345-6789 '4': summary: ERR-ADDR-001 - Address Not Valid value: message: >- The address could not be validated. Please check that the street, city, state, and ZIP are correct and properly formatted. '5': summary: ERR-ADDR-002 - State Mismatch value: message: >- ERR-ADDR-002: The state you provided (Texas) does not match the address entered. The expected state for this address is 'Arizona'. '6': summary: IsPartial Address Error value: message: - Address.steet may not be blank in a non partial address - Address.city may not be blank in a non partial address headers: {} x-apidog-name: Something is wrong with your request '401': description: '' content: application/json: schema: type: object properties: {} x-apidog-orders: [] x-apidog-ignore-properties: [] headers: {} x-apidog-name: Unauthorized '403': description: '' content: application/json: schema: type: object properties: {} x-apidog-orders: [] x-apidog-ignore-properties: [] headers: {} x-apidog-name: Forbidden '404': description: '' content: application/json: schema: type: object properties: {} x-apidog-orders: [] x-apidog-ignore-properties: [] headers: {} x-apidog-name: Transaction Not Found '500': description: '' content: application/json: schema: type: object properties: {} x-apidog-orders: [] x-apidog-ignore-properties: [] headers: {} x-apidog-name: Internal Error x-400:ERR-ADDR-001: description: '' content: application/json: schema: title: '' type: object properties: message: type: string x-apidog-mock: ERR-ADDR-001 description: >- The address could not be validated. Please check that the street, city, state, and ZIP are correct and properly formatted. x-apidog-orders: - message x-apidog-ignore-properties: [] headers: {} x-apidog-name: ERR-ADDR-001 security: - bearer: [] x-apidog-folder: Endpoints/Transactions x-apidog-status: released x-run-in-apidog: https://app.apidog.com/web/project/563651/apis/api-7838825-run components: schemas: ShippingFee: required: - taxCode - salesTaxRates - gtRates type: object properties: manualSalesTax: type: boolean description: >- The tax culculation will be using manualSalesTaxRate value when manualSalesTax is True. default value is False manualSalesTaxRate: type: number description: >- In correlation to the value of manualSalesTax, this numeric value will be used to calculate the sales tand tax amount totalPrice: type: number description: The total price of the shipping fee taxCode: maxLength: 256 minLength: 0 type: string salesTaxRates: &ref_39 $ref: '#/components/schemas/SalesTaxRates' gtRates: &ref_31 $ref: '#/components/schemas/GtRates' description: The shipping fee for the transaction x-apidog-orders: - manualSalesTax - manualSalesTaxRate - totalPrice - taxCode - salesTaxRates - gtRates x-apidog-ignore-properties: [] x-apidog-folder: '' GtRates: type: object properties: countryRate: type: number regionRate: type: number taxRate: type: number x-apidog-orders: - countryRate - regionRate - taxRate x-apidog-ignore-properties: [] x-apidog-folder: '' SalesTaxRates: type: object properties: cityRate: &ref_25 type: number countyRate: &ref_26 type: number stateRate: &ref_27 type: number taxRate: &ref_28 type: number combinedDistrictRate: &ref_29 type: number ratesMetaData: $ref: '#/components/schemas/RatesMetaData' x-apidog-orders: - cityRate - countyRate - stateRate - taxRate - combinedDistrictRate - ratesMetaData x-apidog-ignore-properties: [] x-apidog-folder: '' RatesMetaData: type: object properties: cityDistrictRate: type: number countyDistrictRate: type: number x-apidog-orders: - cityDistrictRate - countyDistrictRate x-apidog-ignore-properties: [] x-apidog-folder: '' externalTimestamps: required: - createdDate - updatedDate type: object properties: createdDate: &ref_1 $ref: '#/components/schemas/timestamp' description: The creation time of the transaction updatedDate: *ref_1 description: >- External timestamps, which should reference the dates in your originating system since these are the timestamps used for sales tax calculation x-apidog-orders: - createdDate - updatedDate x-apidog-ignore-properties: [] x-apidog-folder: '' timestamp: type: string description: >- valid ISO8601 format. Supported formats are 'YYYY-MM-DD'/ 'YYYY-MM-DDTHH:mm:ssZ'/ and 'YYYY-MM-DDTHH:mm:ss±hh:mm' (with a valid time zone offset). x-apidog-folder: '' billingAddress: type: object properties: city: maxLength: 100 minLength: 0 type: string country: maxLength: 50 minLength: 0 type: string county: maxLength: 100 minLength: 0 type: string state: maxLength: 100 minLength: 0 type: string street: maxLength: 200 minLength: 0 type: string region: maxLength: 20 minLength: 0 type: string zip: maxLength: 20 minLength: 0 type: string description: The billing address for the transaction x-apidog-orders: - city - country - county - state - street - region - zip x-apidog-ignore-properties: [] x-apidog-folder: '' Item Request: required: - unitPrice - quantity - name - taxCode type: object properties: unitPrice: type: number description: The price of one unit, can be positive and negative quantity: type: number description: The quantity of the units, must be positive totalPrice: type: number description: >- The total price of the unit prices time the quantity, can be positive and negative, value is before discount and sales tax. If totalPrice exist it will override the unitPrice and quantity calculation description: type: string name: maxLength: 256 minLength: 1 type: string taxCode: maxLength: 256 minLength: 0 type: string manualSalesTax: type: boolean description: >- The tax culculation will be using manualSalesTaxRate value when manualSalesTax is True. default value is False manualSalesTaxRate: maximum: 0.2 type: number description: >- In correlation to the value of manualSalesTax, this numeric value will be used to calculate the sales tand tax amount discount: type: number description: The discount of the line items, must be positive description: An item included in the transaction x-apidog-orders: - unitPrice - quantity - totalPrice - description - name - taxCode - manualSalesTax - manualSalesTaxRate - discount x-apidog-ignore-properties: [] x-apidog-folder: '' transaction Request: required: - externalId - source - items - shippingAddress - customerId - transactionStatus - externalTimestamps - transactionType type: object properties: externalId: maxLength: 256 minLength: 1 type: string description: >- the attribute designed to receive a unique identifier provided by API consumers themselves (e.g. pass your own ID) source: pattern: ^(10|[1-9])$ type: string description: >- a single digit which identifies your different stores, checkout solutions, marketplaces, etc. defined by the API consumers (to avoid external id duplications) documentName: maxLength: 50 minLength: 0 type: string description: The name of the document, as shown in the ERP systems items: type: array items: *ref_2 isTaxInclusive: type: boolean description: >- Indicates whether tax is included in the total items price (true) or added as a separate charge (false). billingAddress: *ref_3 shippingAddress: &ref_6 $ref: '#/components/schemas/shippingAddress' description: The address that the tax calculation based on customerId: type: string description: The Complyt ID of the customer associated with the transaction format: uuid customerExternalId: type: string description: >- The external customer ID to used in addition with customer source to locate a customer instead of using the customerId. If customerID is added, it will be prefererd. customerSource: type: string description: >- The external customer source to used in addition with customer external ID to locate a customer instead of using the customerId. If customerID is added, it will be prefererd. transactionStatus: type: string description: The status of the transaction enum: - ACTIVE - CANCELLED - PAID externalTimestamps: *ref_4 transactionType: type: string description: >- The type of the transaction. Only invoices are considered for nexus tracking and for actual tax calculation enum: - SALES_ORDER - INVOICE - ESTIMATE - REFUND - TAXABLE_REFUND x-apidog-enum: - name: '' value: SALES_ORDER description: '' - name: '' value: INVOICE description: '' - name: '' value: ESTIMATE description: '' - name: '' value: REFUND description: '' - name: '' value: TAXABLE_REFUND description: '' shippingFee: *ref_5 createdFrom: maxLength: 256 minLength: 0 type: string description: >- The external ID of the document that preceded this transaction creation (e.g., when creating an invoice, you can pass the ID of the sales order that it originated from here) transactionLevelDiscount: type: number description: The discount to apply on the overall transaction transactionFilingStatus: type: string description: >- Indicates the status of the transaction in relation to its submission to a specific state. Possible values include: - NOT_FILED: The transaction has not been submitted to the state. - FILED: The transaction has been successfully submitted to the state. enum: - NOT_FILED - FILED currency: type: string description: The currency of the transaction. not mandatory refRate: type: number description: The manual currency exchange rate subsidiary: type: string isRefundLinked: type: boolean description: >- If set to true, the sales tax will be taken from the invoice specified in the createdFrom field and returned as the refund's salesTax.amount description: A transaction between the API consumer and a customer x-apidog-orders: - externalId - source - documentName - items - isTaxInclusive - billingAddress - shippingAddress - customerId - customerExternalId - customerSource - transactionStatus - externalTimestamps - transactionType - shippingFee - createdFrom - transactionLevelDiscount - transactionFilingStatus - currency - refRate - subsidiary - isRefundLinked x-apidog-ignore-properties: [] x-apidog-folder: '' shippingAddress: required: - city - country - state - street - zip - isPartial type: object properties: city: maxLength: 100 minLength: 0 type: string country: &ref_7 maxLength: 50 minLength: 0 type: string county: &ref_8 maxLength: 100 minLength: 0 type: string state: maxLength: 100 minLength: 0 type: string street: maxLength: 200 minLength: 0 type: string region: &ref_9 maxLength: 20 minLength: 0 type: string zip: maxLength: 20 minLength: 0 type: string isPartial: type: boolean description: whether country, city or street are necessary matchedAddressData: type: object description: Details of the real address in the US based on the request address. properties: address: type: object description: Matched address details. properties: city: &ref_10 type: string description: City of the matched address. country: &ref_11 type: string description: Country of the matched address. county: &ref_12 type: string description: County of the matched address. state: &ref_13 type: string description: State of the matched address. zip: &ref_14 type: string description: ZIP code of the matched address. required: - city - country - county - state - zip x-apidog-orders: &ref_15 - city - country - county - state - zip x-apidog-ignore-properties: [] scoring: type: object description: Scoring data for the matched address. properties: matchLevel: &ref_16 type: string description: Overall match level. score: &ref_17 type: number description: Overall match score. fieldScore: type: object description: Individual field match scores. properties: countryMatch: &ref_18 type: string description: Country match status. stateMatch: &ref_19 type: string description: State match status. cityMatch: &ref_20 type: string description: City match status. zipMatch: &ref_21 type: string description: ZIP code match status. required: - countryMatch - stateMatch - cityMatch - zipMatch x-apidog-orders: &ref_22 - countryMatch - stateMatch - cityMatch - zipMatch x-apidog-ignore-properties: [] required: - matchLevel - score - fieldScore x-apidog-orders: &ref_23 - matchLevel - score - fieldScore x-apidog-ignore-properties: [] required: - address - scoring x-apidog-orders: &ref_24 - address - scoring x-apidog-ignore-properties: [] description: The shipping address for the transaction x-apidog-orders: - city - country - county - state - street - region - zip - isPartial - matchedAddressData x-apidog-ignore-properties: [] x-apidog-folder: '' shippingAddress Copy: required: - country type: object properties: country: maxLength: 50 minLength: 0 type: string region: maxLength: 20 minLength: 0 type: string city: maxLength: 100 minLength: 0 type: string county: maxLength: 100 minLength: 0 type: string state: maxLength: 100 minLength: 0 type: string street: maxLength: 200 minLength: 0 type: string zip: maxLength: 20 minLength: 0 type: string isPartial: type: boolean description: whether country, city or street are necessary description: The shipping address for the transaction x-apidog-orders: - country - region - city - county - state - street - zip - isPartial x-apidog-ignore-properties: [] x-apidog-folder: '' transaction Response: required: - externalId - source - items - shippingAddress - customerId - transactionStatus - externalTimestamps - transactionType type: object properties: complytId: type: string description: >- The unique identifier in Complyt of the transaction. Required only on update operations. format: uuid externalId: maxLength: 256 minLength: 1 type: string description: >- the attribute designed to receive a unique identifier provided by API consumers themselves (e.g. pass your own ID) source: pattern: ^(10|[1-9])$ type: string description: >- a single digit which identifies your different stores, checkout solutions, marketplaces, etc. defined by the API consumers (to avoid external id duplications) documentName: maxLength: 50 minLength: 0 type: string description: The name of the document, as shown in the ERP systems items: type: array items: type: object properties: {} isTaxInclusive: type: boolean description: >- Indicates whether tax is included in the total items price (true) or added as a separate charge (false). billingAddress: *ref_3 shippingAddress: description: The address that the tax calculation based on type: object x-apidog-refs: 01J44R8KM23RJAE06H7E8C4X6V: *ref_6 x-apidog-orders: - 01J44R8KM23RJAE06H7E8C4X6V properties: city: maxLength: 100 minLength: 0 type: string country: *ref_7 county: *ref_8 state: maxLength: 100 minLength: 0 type: string street: maxLength: 200 minLength: 0 type: string region: *ref_9 zip: maxLength: 20 minLength: 0 type: string isPartial: type: boolean description: whether country, city or street are necessary matchedAddressData: type: object description: >- Details of the real address in the US based on the request address. properties: address: type: object description: Matched address details. properties: city: *ref_10 country: *ref_11 county: *ref_12 state: *ref_13 zip: *ref_14 required: - city - country - county - state - zip x-apidog-orders: *ref_15 x-apidog-ignore-properties: [] scoring: type: object description: Scoring data for the matched address. properties: matchLevel: *ref_16 score: *ref_17 fieldScore: type: object description: Individual field match scores. properties: countryMatch: *ref_18 stateMatch: *ref_19 cityMatch: *ref_20 zipMatch: *ref_21 required: - countryMatch - stateMatch - cityMatch - zipMatch x-apidog-orders: *ref_22 x-apidog-ignore-properties: [] required: - matchLevel - score - fieldScore x-apidog-orders: *ref_23 x-apidog-ignore-properties: [] required: - address - scoring x-apidog-orders: *ref_24 x-apidog-ignore-properties: [] required: - city - country - state - street - zip - isPartial x-apidog-ignore-properties: - city - country - county - state - street - region - zip - isPartial - matchedAddressData customerId: type: string description: The Complyt ID of the customer associated with the transaction format: uuid customer: &ref_40 type: object properties: {} salesTax: type: object x-apidog-refs: 01J0T8WD2B17KYSB5AKB8TA4AN: &ref_41 x-apidog-overrides: salesTaxRates: &ref_34 description: >- If sales tax are applied, this field will hold the relevant data type: object x-apidog-refs: 01J0T9092VFZKAMZBBE36B3SZF: &ref_30 type: object properties: {} x-apidog-orders: - 01J0T9092VFZKAMZBBE36B3SZF properties: cityRate: *ref_25 countyRate: *ref_26 stateRate: *ref_27 taxRate: *ref_28 combinedDistrictRate: *ref_29 ratesMetaData: *ref_30 x-apidog-ignore-properties: - cityRate - countyRate - stateRate - taxRate - combinedDistrictRate - ratesMetaData gtRates: *ref_31 rate: &ref_33 type: number description: >- wheter global tax / vat / sales tax are applied, this field will hold the final rate that is applied on the transaction amount: &ref_32 type: number description: >- wheter global tax / vat / sales tax are applied, this field will hold the final amount that is applied on the transaction type: object properties: {} x-apidog-orders: - 01J0T8WD2B17KYSB5AKB8TA4AN properties: amount: *ref_32 rate: *ref_33 salesTaxRates: *ref_34 gtRates: *ref_31 x-apidog-ignore-properties: - amount - rate - salesTaxRates - gtRates transactionStatus: type: string description: The status of the transaction enum: - ACTIVE - CANCELLED - PAID internalTimestamps: &ref_42 $ref: '#/components/schemas/internalTimestamps' externalTimestamps: *ref_4 transactionType: type: string description: >- The type of the transaction. Only invoices are considered for nexus tracking and for actual tax calculation enum: - SALES_ORDER - INVOICE - ESTIMATE - REFUND - TAXABLE_REFUND x-apidog-enum: - name: '' value: SALES_ORDER description: '' - name: '' value: INVOICE description: '' - name: '' value: ESTIMATE description: '' - name: '' value: REFUND description: '' - name: '' value: TAXABLE_REFUND description: '' shippingFee: *ref_5 createdFrom: maxLength: 256 minLength: 0 type: string description: >- The external ID of the document that preceded this transaction creation (e.g., when creating an invoice, you can pass the ID of the sales order that it originated from here) taxableItemsAmount: type: number description: The amount of taxable items in the transaction, tax excluded tangibleItemsAmount: type: number description: The amount of tangible items in the transaction, tax excluded totalItemsAmount: type: number description: >- The total amount of items in the transaction. tax and discount excluded totalDiscount: type: number description: The total discount of all the items combined. calculated on save transactionLevelDiscount: type: number description: The discount to apply on the overall transaction finalTransactionAmount: type: number description: The total amount of the transaction after discounts and taxes transactionFilingStatus: type: string description: >- Indicates the status of the transaction in relation to its submission to a specific state. Possible values include: - NOT_FILED: The transaction has not been submitted to the state. - FILED: The transaction has been successfully submitted to the state. enum: - NOT_FILED - FILED currency: type: string description: The currency of the transaction. not mandatory refRate: type: number description: The manual currency exchange rate exchangeRateInfo: $ref: '#/components/schemas/ExchangeRateInfo' description: Details regarding the currency conversion subsidiary: type: string description: A transaction between the API consumer and a customer x-apidog-orders: - complytId - externalId - source - documentName - items - isTaxInclusive - billingAddress - shippingAddress - customerId - customer - salesTax - transactionStatus - internalTimestamps - externalTimestamps - transactionType - shippingFee - createdFrom - taxableItemsAmount - tangibleItemsAmount - totalItemsAmount - totalDiscount - transactionLevelDiscount - finalTransactionAmount - transactionFilingStatus - currency - refRate - exchangeRateInfo - subsidiary x-apidog-ignore-properties: [] x-apidog-folder: '' ExchangeRateInfo: type: object properties: totalItemsAmountInUsd: type: number description: The transaction totalItemsAmount converted to USD transactionSalesTaxInUsd: type: number description: The transaction salesTax.amount converted to USD finalTransactionAmountInUsd: type: number description: The transaction final amount converted to USD (items and sales tax) fromCurrency: type: string description: 'The original currency specified in the transaction ' toCurrency: type: string description: The target currency (USD) fxRate: type: number description: The exchange rate that applied on the transaction source: type: string enum: - COMPLYT - CLIENT x-apidog-enum: - value: COMPLYT name: '' description: '' - value: CLIENT name: '' description: '' description: >- The source of fxRate. If entered manually in refRate then the value would be CLIENT. isExchangeRateEstimated: type: boolean description: >- Flag that specified whether the exchange rate is estimate. true for future transactions exchangeRateDate: *ref_1 x-apidog-orders: - totalItemsAmountInUsd - transactionSalesTaxInUsd - finalTransactionAmountInUsd - fromCurrency - toCurrency - fxRate - source - isExchangeRateEstimated - exchangeRateDate x-apidog-ignore-properties: [] x-apidog-folder: '' internalTimestamps: required: - createdDate - updatedDate type: object properties: createdDate: *ref_1 updatedDate: *ref_1 description: read-only. The APIs internal timestamps for this resource x-apidog-orders: - createdDate - updatedDate x-apidog-ignore-properties: [] x-apidog-folder: '' transaction: required: - externalId - source - items - shippingAddress - customerId - transactionStatus - externalTimestamps - transactionType type: object properties: complytId: type: string description: The unique identifier in Complyt of the transaction format: uuid externalId: maxLength: 256 minLength: 1 type: string description: >- the attribute designed to receive a unique identifier provided by API consumers themselves (e.g. pass your own ID) source: pattern: ^(10|[1-9])$ type: string description: >- a single digit which identifies your different stores, checkout solutions, marketplaces, etc. defined by the API consumers (to avoid external id duplications) documentName: maxLength: 50 minLength: 0 type: string description: The name of the document, as shown in the ERP systems items: type: array items: type: object x-apidog-refs: 01J0T95FS2F980WDS7E5YN0429: $ref: '#/components/schemas/Item' x-apidog-overrides: jurisdictionalSalesTaxRules: &ref_38 description: >- Will hold the relevant rules that are applied on the item. country rules if gt / vat, state rules if USA type: object x-apidog-refs: 01J0T98F8EMJEDKPP2F77WJG1J: &ref_50 $ref: '#/components/schemas/JurisdictionalSalesTaxRules' x-apidog-overrides: cities: &ref_36 type: object additionalProperties: &ref_35 $ref: '#/components/schemas/SubJurisdictionalTaxRules' x-apidog-orders: [] description: >- Holds a list of cities specifically sales tax rules that may applied to the item. If no city rule are applied, this will be null. This field is only for USA transactions. properties: {} x-apidog-ignore-properties: [] regions: &ref_37 type: object additionalProperties: *ref_35 x-apidog-orders: [] description: >- Holds a list of regions specifically gt / vat rules that may applied to the item. If no region rule are applied, this will be null. This field is only for gt / vat transactions. properties: {} x-apidog-ignore-properties: [] x-apidog-orders: - 01J0T98F8EMJEDKPP2F77WJG1J properties: name: &ref_57 maxLength: 256 minLength: 0 type: string abbreviation: &ref_58 maxLength: 256 minLength: 0 type: string taxable: &ref_59 type: boolean specialTreatment: &ref_60 type: boolean calculationType: &ref_61 type: string enum: - FIXED - PERCENTAGE description: &ref_62 maxLength: 256 minLength: 0 type: string calculationValue: &ref_63 type: number cities: *ref_36 regions: *ref_37 x-apidog-ignore-properties: - name - abbreviation - taxable - specialTreatment - calculationType - description - calculationValue - cities - regions x-apidog-orders: - 01J0T95FS2F980WDS7E5YN0429 properties: unitPrice: &ref_43 type: number description: The price of one unit, can be positive and negative quantity: &ref_44 type: number description: The quantity of the units, must be positive totalPrice: &ref_45 type: number description: >- The total price of the unit prices time the quantity, can be positive and negative, value is before discount and sales tax calculatedTotal: &ref_46 type: number description: >- The calculated price of the items. represents the total price (or amount time quantity if not provided), after discount. calculated on run time description: &ref_47 type: string name: &ref_48 maxLength: 256 minLength: 1 type: string taxCode: &ref_49 maxLength: 256 minLength: 0 type: string jurisdictionalSalesTaxRules: *ref_38 salesTaxRates: *ref_39 gtRates: *ref_31 manualSalesTax: &ref_51 type: boolean manualSalesTaxRate: &ref_52 maximum: 0.2 type: number discount: &ref_53 type: number description: The discount of the line items, must be positive relativeTransactionDiscount: &ref_54 type: number description: >- The relative transaction level discount to apply on a specific item. calculated on run time tangibleCategory: &ref_55 type: string enum: - TANGIBLE - INTANGIBLE taxableCategory: &ref_56 type: string enum: - TAXABLE - NOT_TAXABLE required: - name - taxCode x-apidog-ignore-properties: - unitPrice - quantity - totalPrice - calculatedTotal - description - name - taxCode - jurisdictionalSalesTaxRules - salesTaxRates - gtRates - manualSalesTax - manualSalesTaxRate - discount - relativeTransactionDiscount - tangibleCategory - taxableCategory isTaxInclusive: type: boolean description: >- Indicates whether tax is included in the total items price (true) or added as a separate charge (false). billingAddress: *ref_3 shippingAddress: *ref_6 customerId: type: string description: The Complyt ID of the customer associated with the transaction format: uuid customer: *ref_40 salesTax: type: object x-apidog-refs: 01J0T8WD2B17KYSB5AKB8TA4AN: *ref_41 x-apidog-orders: - 01J0T8WD2B17KYSB5AKB8TA4AN properties: amount: type: number description: >- wheter global tax / vat / sales tax are applied, this field will hold the final amount that is applied on the transaction rate: type: number description: >- wheter global tax / vat / sales tax are applied, this field will hold the final rate that is applied on the transaction salesTaxRates: description: If sales tax are applied, this field will hold the relevant data type: object x-apidog-refs: 01J0T9092VFZKAMZBBE36B3SZF: *ref_30 x-apidog-orders: - 01J0T9092VFZKAMZBBE36B3SZF properties: cityRate: *ref_25 countyRate: *ref_26 stateRate: *ref_27 taxRate: *ref_28 combinedDistrictRate: *ref_29 ratesMetaData: *ref_30 x-apidog-ignore-properties: - cityRate - countyRate - stateRate - taxRate - combinedDistrictRate - ratesMetaData gtRates: *ref_31 x-apidog-ignore-properties: - amount - rate - salesTaxRates - gtRates transactionStatus: type: string description: The status of the transaction enum: - ACTIVE - CANCELLED - PAID internalTimestamps: *ref_42 externalTimestamps: *ref_4 transactionType: type: string description: >- The type of the transaction. Only invoices are considered for nexus tracking and for actual tax calculation enum: - SALES_ORDER - INVOICE - ESTIMATE - REFUND - TAXABLE_REFUND x-apidog-enum: - value: SALES_ORDER name: '' description: '' - value: INVOICE name: '' description: '' - value: ESTIMATE name: '' description: '' - value: REFUND name: '' description: '' - value: TAXABLE_REFUND name: '' description: '' shippingFee: *ref_5 createdFrom: maxLength: 256 minLength: 0 type: string description: >- The external ID of the document that preceded this transaction creation (e.g., when creating an invoice, you can pass the ID of the sales order that it originated from here) taxableItemsAmount: type: number description: The amount of taxable items in the transaction tangibleItemsAmount: type: number description: The amount of tangible items in the transaction totalItemsAmount: type: number description: >- The total amount of items in the transaction. tax and discount excluded totalDiscount: type: number description: The total discount of all the items combined. calculated on save transactionLevelDiscount: type: number description: The discount to apply on the overall transaction finalTransactionAmount: type: number description: The total amount of the transaction after discounts taxes transactionFilingStatus: type: string description: >- Indicates the status of the transaction in relation to its submission to a specific state. Possible values include: - NOT_FILED: The transaction has not been submitted to the state. - FILED: The transaction has been successfully submitted to the state. enum: - NOT_FILED - FILED currency: type: string description: The currency of the transaction. not mandatory subsidiary: type: string description: A transaction between the API consumer and a customer x-apidog-orders: - complytId - externalId - source - documentName - items - isTaxInclusive - billingAddress - shippingAddress - customerId - customer - salesTax - transactionStatus - internalTimestamps - externalTimestamps - transactionType - shippingFee - createdFrom - taxableItemsAmount - tangibleItemsAmount - totalItemsAmount - totalDiscount - transactionLevelDiscount - finalTransactionAmount - transactionFilingStatus - currency - subsidiary x-apidog-ignore-properties: [] x-apidog-folder: '' Item: required: - name - taxCode type: object properties: unitPrice: *ref_43 quantity: *ref_44 totalPrice: *ref_45 calculatedTotal: *ref_46 description: *ref_47 name: *ref_48 taxCode: *ref_49 jurisdictionalSalesTaxRules: *ref_50 salesTaxRates: *ref_39 gtRates: *ref_31 manualSalesTax: *ref_51 manualSalesTaxRate: *ref_52 discount: *ref_53 relativeTransactionDiscount: *ref_54 tangibleCategory: *ref_55 taxableCategory: *ref_56 description: An item included in the transaction x-apidog-orders: - unitPrice - quantity - totalPrice - calculatedTotal - description - name - taxCode - jurisdictionalSalesTaxRules - salesTaxRates - gtRates - manualSalesTax - manualSalesTaxRate - discount - relativeTransactionDiscount - tangibleCategory - taxableCategory x-apidog-ignore-properties: [] x-apidog-folder: '' JurisdictionalSalesTaxRules: type: object properties: name: *ref_57 abbreviation: *ref_58 taxable: *ref_59 specialTreatment: *ref_60 calculationType: *ref_61 description: *ref_62 calculationValue: *ref_63 cities: type: object additionalProperties: *ref_35 x-apidog-orders: [] properties: {} x-apidog-ignore-properties: [] regions: type: object additionalProperties: *ref_35 x-apidog-orders: [] properties: {} x-apidog-ignore-properties: [] x-apidog-orders: - name - abbreviation - taxable - specialTreatment - calculationType - description - calculationValue - cities - regions x-apidog-ignore-properties: [] x-apidog-folder: '' SubJurisdictionalTaxRules: type: object properties: name: type: string abbreviation: type: string taxable: type: boolean specialTreatment: type: boolean calculationType: type: string enum: - FIXED - PERCENTAGE description: type: string calculationValue: type: number x-apidog-orders: - name - abbreviation - taxable - specialTreatment - calculationType - description - calculationValue x-apidog-ignore-properties: [] x-apidog-folder: '' SalesTax: type: object properties: amount: type: number rate: type: number salesTaxRates: *ref_39 gtRates: *ref_31 description: >- The sales tax breakdown for the transaction, including the amount and rates by jurisdictions. if tax may apply, contains either salestax rates or gt rates x-apidog-orders: - amount - rate - salesTaxRates - gtRates x-apidog-ignore-properties: [] x-apidog-folder: '' Customer: required: - externalId - source - externalTimestamps type: object properties: complytId: type: string description: The unique identifier in Complyt of the customer format: uuid externalId: maxLength: 256 minLength: 1 type: string description: >- the attribute designed to receive a unique identifier provided by API consumers themselves (e.g. pass your own ID) source: pattern: ^(10|[1-9])$ type: string description: >- a single digit which identifies your different stores, checkout solutions, marketplaces, etc. defined by the API consumers (to avoid external id duplications) name: maxLength: 256 minLength: 1 type: string description: The customer's name address: type: object x-apidog-refs: 01JGH7DHX4HAF9P7RKAMV2S15X: $ref: '#/components/schemas/addressOfCustomer' x-apidog-overrides: isPartial: null x-apidog-orders: - 01JGH7DHX4HAF9P7RKAMV2S15X properties: city: &ref_64 maxLength: 100 minLength: 0 type: string country: &ref_65 maxLength: 50 minLength: 0 type: string county: &ref_66 maxLength: 100 minLength: 0 type: string state: &ref_67 maxLength: 100 minLength: 0 type: string street: &ref_68 maxLength: 200 minLength: 0 type: string region: &ref_69 maxLength: 20 minLength: 0 type: string zip: &ref_70 maxLength: 20 minLength: 0 type: string x-apidog-ignore-properties: - city - country - county - state - street - region - zip email: type: string description: An (Optional) Email address associated with the customer customerType: type: string description: >- Indicates whether the customer is 'retail'/'reseller'/'marketplace'. Defaults to 'retail' if no customer type is provided enum: - RETAIL - MARKETPLACE - RESELLER - RETAIL_EXEMPT internalTimestamps: *ref_42 externalTimestamps: *ref_4 comment: maxLength: 200 minLength: 0 type: string taxNumber: type: string description: An (Optional) tax number to be associated with the customer description: The buyer. All transactions are associated with a customer x-apidog-orders: - complytId - externalId - source - name - address - email - customerType - internalTimestamps - externalTimestamps - comment - taxNumber x-apidog-ignore-properties: [] x-apidog-folder: '' addressOfCustomer: type: object properties: city: *ref_64 country: *ref_65 county: *ref_66 state: *ref_67 street: *ref_68 region: *ref_69 zip: *ref_70 isPartial: type: boolean description: The customer's Address x-apidog-orders: - city - country - county - state - street - region - zip - isPartial x-apidog-ignore-properties: [] x-apidog-folder: '' Item Response: required: - unitPrice - quantity - name - taxCode type: object properties: unitPrice: type: number description: The price of one unit, can be positive and negative quantity: type: number description: The quantity of the units, must be positive totalPrice: type: number description: >- The total price of the unit prices time the quantity, can be positive and negative, value is before discount and sales tax calculatedTotal: type: number description: >- The calculated price of the items. represents the total price (or amount time quantity if not provided), after discount. calculated on run time description: type: string name: maxLength: 256 minLength: 1 type: string taxCode: maxLength: 256 minLength: 0 type: string jurisdictionalSalesTaxRules: *ref_50 salesTaxRates: *ref_39 gtRates: *ref_31 manualSalesTax: type: boolean description: >- The tax culculation will be using manualSalesTaxRate value when manualSalesTax is True. default value is False manualSalesTaxRate: maximum: 0.2 type: number description: >- In correlation to the value of manualSalesTax, this numeric value will be used to calculate the sales tand tax amount discount: type: number description: The discount of the line items, must be positive relativeTransactionDiscount: type: number description: >- The relative transaction level discount to apply on a specific item. calculated on run time tangibleCategory: type: string enum: - TANGIBLE - INTANGIBLE taxableCategory: type: string enum: - TAXABLE - NOT_TAXABLE description: An item included in the transaction x-apidog-orders: - unitPrice - quantity - totalPrice - calculatedTotal - description - name - taxCode - jurisdictionalSalesTaxRules - salesTaxRates - gtRates - manualSalesTax - manualSalesTaxRate - discount - relativeTransactionDiscount - tangibleCategory - taxableCategory x-apidog-ignore-properties: [] x-apidog-folder: '' securitySchemes: bearer: type: http scheme: bearer servers: - url: https://sandbox.complyt.io description: SandBox security: [] ```