openapi: 3.1.0 x-stoplight: id: 32pxuah6hmb9a servers: - description: Production url: 'https://api.codat.io' info: title: Commerce API version: 2.1.0 contact: name: Codat email: support@codat.io summary: 'Codat''s standardized API for accessing commerce data ' description: |- Codat's Commerce API allows you to access standardised data from over 11 commerce and POS systems. Standardize how you connect to your customers’ payment, PoS, and eCommerce systems. Retrieve orders, payouts, payments, and product data in the same way for all the leading commerce platforms. [Read more...](https://docs.codat.io/commerce-api/overview) [See our OpenAPI spec](https://github.com/codatio/oas) termsOfService: 'https://www.codat.io/legals/' security: - auth_header: [] tags: - name: Customers description: Retrieve standardized data from linked commerce platforms. - name: Disputes description: Retrieve standardized data from linked commerce platforms. - name: Company info description: Retrieve standardized data from linked commerce platforms. - name: Locations description: Retrieve standardized data from linked commerce platforms. - name: Orders description: Retrieve standardized data from linked commerce platforms. - name: Payments description: Retrieve standardized data from linked commerce platforms. - name: Products description: Retrieve standardized data from linked commerce platforms. - name: Tax components description: Retrieve standardized data from linked commerce platforms. - name: Transactions description: Retrieve standardized data from linked commerce platforms. paths: '/companies/{companyId}/connections/{connectionId}/data/commerce-customers': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: List customers tags: - Customers responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: results: type: array items: $id: 'https://schemas.codat.io/datamodel/commerce/customer.json' title: Customer description: Represents a customer who has placed an order in the commerce system" x-stoplight: id: avuh8zncanxa4 type: object x-datatype: dataTypeId: f51d742e-6797-4ae0-8b3c-63cc6c9d1972 databaseId: 24 name: commerce-customers domain: commerce singluar: customer plural: customers fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: customerName: type: string description: Name of the customer example: Fred Smith emailAddress: type: string description: Email address of the customer example: fred.smith@myCompany.com phone: title: Phone Number x-stoplight: id: 1ch48ghi554eb type: string description: A phone number examples: - +44 25691 154789 - (877) 492-8687 - 01224 658 999 defaultCurrency: allOf: - description: | Default currency of any transactional data for the customer, for example, orders or payments - title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR addresses: type: array description: Addresses of the customer items: allOf: - title: Address x-stoplight: id: lih0rzmqm2onw type: object properties: type: description: The type of the address type: string enum: - Billing - Delivery - Order - Inventory - Unknown line1: description: The first line of the address type: string line2: description: The second line of the address type: string city: description: 'The third line of the address, or city' type: string region: description: 'The fourth line of the address, or region' type: string country: description: The country for the address type: string postalCode: description: The postal (or zip) code for the address type: string - properties: type: enum: - Billing - Delivery note: type: string description: Any additional information about the customer - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: type: object x-internal: true required: - self - current properties: self: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference current: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference next: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference previous: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' examples: example-1: value: results: - id: 13d946f0-c5d5-42bc-b092-97ece17923ab amount: 194.12 currency: GBP paymentMethodRef: id: EILBDVJVNUAGVKRQ name: AliPay status: Pending paymentProvider: Amazon Pay dueDate: '2019-08-24T14:15:22Z' createdDate: '2019-08-24T14:15:22Z' modifiedDate: '2019-08-24T14:15:22Z' sourceModifiedDate: '2019-08-24T14:15:22Z' _links: self: href: ../dictionary current: href: ../dictionary next: href: ../dictionary previous: href: ../dictionary pageNumber: 0 pageSize: 0 totalResults: 0 operationId: list-commerce-customers description: List all commerce customers for the given company and data connection parameters: - name: page in: query required: true schema: type: integer format: int32 minimum: 0 example: 1 default: 1 description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: 1318joqblpp4e - name: pageSize in: query schema: type: integer format: int32 default: 100 example: 100 minimum: 1 maximum: 5000 description: 'Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: s2ika6rltk5y6 - name: query in: query required: false schema: type: string description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).' x-stoplight: id: gupdb9kt30hfq - name: orderBy in: query required: false schema: type: string example: '-modifiedDate' description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).' x-stoplight: id: 4je9lwo02netu '/companies/{companyId}/connections/{connectionId}/data/commerce-disputes': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: List disputes tags: - Disputes responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: results: type: array items: title: Dispute x-stoplight: id: ivpv6516qf630 type: object x-datatype: id: cf7f81a2-13a7-4f63-8862-604dd7bdfd2a databaseId: 25 name: commerce-disputes domain: commerce singluar: dispute plural: disputes fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: disputedTransactions: description: Link to the source event which triggered this transaction. allOf: - title: TransactionSourceRef x-stoplight: id: ydj5jokox9hvp type: object allOf: - title: Record Ref x-internal: true type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ type: description: The type of record being referenced. type: string required: - id - type description: '' - properties: type: enum: - Fee - Order - Payment - ServiceCharge - Unknown totalAmount: description: Total transaction amount that is under dispute. type: number examples: - 194.12 - -283.56 - 0 currency: description: Currency of the disputed transaction. title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string format: ISO4217 examples: - GBP - USD - EUR status: description: Current status of the dispute type: string enum: - Won - Lost - Accepted - Processing - ChargeRefunded - EvidenceRequired - InquiryEvidenceRequired - InquiryProcessing - InquiryClosed - WaitingThirdParty - Unknown example: EvidenceRequired reason: description: Reason for the dispute type: string examples: - Unhappy with product dueDate: description: Date when the next action in the dispute resolution is due type: string example: '2022-10-23T00:00:00Z' title: Date Time allOf: - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time required: - currency - type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: type: object x-internal: true required: - self - current properties: self: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference current: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference next: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference previous: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' examples: Example: value: results: - id: 13d946f0-c5d5-42bc-b092-97ece17923ab disputedTransactions: id: 13d946f0-c5d5-42bc-b092-97ece17923ab type: Fee totalAmount: 194.12 currency: GBP status: Won reason: Unhappy with product dueDate: '2021-03-29T14:39:55' createdDate: '2019-08-24T14:15:22Z' modifiedDate: '2019-08-24T14:15:22Z' sourceModifiedDate: '2019-08-24T14:15:22Z' _links: self: href: ../dictionary current: href: ../dictionary next: href: ../dictionary previous: href: ../dictionary pageNumber: 0 pageSize: 0 totalResults: 0 operationId: list-commerce-disputes description: List commerce disputes parameters: - name: page in: query required: true schema: type: integer format: int32 minimum: 0 example: 1 default: 1 description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: 1318joqblpp4e - name: pageSize in: query schema: type: integer format: int32 default: 100 example: 100 minimum: 1 maximum: 5000 description: 'Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: s2ika6rltk5y6 - name: query in: query required: false schema: type: string description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).' x-stoplight: id: gupdb9kt30hfq - name: orderBy in: query required: false schema: type: string example: '-modifiedDate' description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).' x-stoplight: id: 4je9lwo02netu '/companies/{companyId}/connections/{connectionId}/data/commerce-info': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: Get company info tags: - Company info responses: '200': description: OK content: application/json: schema: title: Company Info description: | In the Codat system, company information includes standard commercial details about a linked company, such as their address, phone number, and company registration. x-stoplight: id: d7on55ll1hvqj type: object x-datatype: dataTypeId: d68f4a5e-f1f8-40f0-a28d-565ef0733fb1 databaseId: 33 name: commerce-companyInfo domain: commerce singluar: company infomation plural: company infomation fetchMode: single properties: companyName: type: string description: The name of the company example: Codat commercePlatformRef: type: string description: Identifier or reference for the company in the commerce platform companyLegalName: type: string description: The full legal name of the company example: Codat Limited addresses: type: array description: Addresses associated with the company items: allOf: - title: Address x-stoplight: id: lih0rzmqm2onw type: object properties: type: description: The type of the address type: string enum: - Billing - Delivery - Order - Inventory - Unknown line1: description: The first line of the address type: string line2: description: The second line of the address type: string city: description: 'The third line of the address, or city' type: string region: description: 'The fourth line of the address, or region' type: string country: description: The country for the address type: string postalCode: description: The postal (or zip) code for the address type: string - properties: type: enum: - Billing - Delivery phoneNumbers: type: array description: Phone numbers associated with the company items: type: object properties: number: title: Phone Number x-stoplight: id: 1ch48ghi554eb type: string description: A phone number examples: - +44 25691 154789 - (877) 492-8687 - 01224 658 999 type: description: The type of phone number type: string enum: - Primary - Landline - Mobile - Fax - Unknown required: - number - type webLinks: description: Web links associated with the company type: array items: properties: type: description: The type of the weblink type: string enum: - Website - Social - Unknown url: description: The full URL for the weblink type: string format: url example: type: Website url: 'https://codat.io' registrationNumber: description: The registration number of the company type: string examples: - 10480375 baseCurrency: title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR accountBalances: description: The available and current cash balances for the company's accounts type: array items: type: object properties: available: description: The account's current balance type: number format: decimal pending: description: Funds that are not yet available in the balance type: number format: decimal reserved: description: Funds reserved as holdings type: number format: decimal currency: description: The currency of the account allOf: - title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR sourceUrls: description: 'URL addresses for the originating system. For example, potential use cases include ''deeplinking'' to the originating system' type: object additionalProperties: type: string example: url1: 'https://connect.sandbox.com/v2/customers' url2: 'https://connect.sandbox.com/v2/disputes' allOf: - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time operationId: get-commerce-info description: |- Retrieve information about the company, as seen in the commerce platform. This may include information like addresses, tax registration details and social media or website information. '/companies/{companyId}/connections/{connectionId}/data/commerce-locations': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: List locations tags: - Locations responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: results: type: array items: title: Locations x-stoplight: id: 2d4g3i124e1ea type: object x-datatype: dataTypeId: 6fe79975-e07b-45ba-b878-25329dddd94a databaseId: 34 name: commerce-locations domain: commerce singluar: location plural: locations fetchMode: multiple description: | The Locations datatype holds information on geographic locations at which stocks of products may be held, as referenced in the Products data type. Locations also holds information on geographic locations where orders were placed, as referenced in the Orders data type. From the Locations endpoints you can retrieve: A list of all the Locations of a commerce company: `GET /companies/{companyId}/connections/{connectionId}/data/commerce-locations`. The details of an individual location: `GET /companies/{companyId}/connections/{connectionId}/data/commerce-locations/{locationId}`. allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: name: description: Name of this location type: string address: description: Address associated with the location allOf: - title: Address x-stoplight: id: lih0rzmqm2onw type: object properties: type: description: The type of the address type: string enum: - Billing - Delivery - Order - Inventory - Unknown line1: description: The first line of the address type: string line2: description: The second line of the address type: string city: description: 'The third line of the address, or city' type: string region: description: 'The fourth line of the address, or region' type: string country: description: The country for the address type: string postalCode: description: The postal (or zip) code for the address type: string - properties: type: enum: - Billing - Delivery - Inventory - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: type: object x-internal: true required: - self - current properties: self: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference current: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference next: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference previous: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' examples: Example: value: results: - id: 13d946f0-c5d5-42bc-b092-97ece17923ab name: string address: type: Billing line1: string line2: string city: string region: string country: string postalCode: string modifiedDate: '2019-08-24T14:15:22Z' sourceModifiedDate: '2019-08-24T14:15:22Z' _links: self: href: ../dictionary current: href: ../dictionary next: href: ../dictionary previous: href: ../dictionary pageNumber: 0 pageSize: 0 totalResults: 0 operationId: list-commerce-locations description: |- Retrieve a list of locations as seen in the commerce platform. A `location` is a geographic place at which stocks of products may be held, or from where orders were placed. '/companies/{companyId}/connections/{connectionId}/data/commerce-orders': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: List orders tags: - Orders responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: results: type: array items: title: Orders x-stoplight: id: bg1uwd537qhia type: object x-datatype: dataTypeId: 6e57c403-248d-4851-96fb-d7c903cd8929 databaseId: 22 name: commerce-orders domain: commerce singluar: order plural: orders fetchMode: multiple description: | Orders contain the transaction details for all products sold by the company, and include details of any payments, service charges, or refunds related to each order. From the Orders endpoints you can retrieve: A list of all the orders for a commerce company: `GET /companies/{companyId}/connections/{connectionId}/data/commerce-orders`. The details of an individual order: `GET /companies/{companyId}/connections/{connectionId}/data/commerce-orders/{orderId}`. Note that for refunds `quantity` is a negative value and `unitPrice` is a positive value. allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - properties: orderNumber: type: string description: Friendly reference for the order in the commerce or point of sale platform. country: description: |- The Codat country property is returned as it was provided in the underlying platform by the company without any formatting on our part. Depending on the platform the value of this property will either be an ISO 3166 code (2-alpha or 3-alpha) or free-form text returned as a string name in our model. For POST operations against platforms that demand a specific format for the country code, we have documented accepted values in the [options](https://docs.codat.io/codat-api#/operations/get-companies-companyId-connections-connectionId-push) endpoint. type: string format: ISO3166 Alpha-3 examples: - GBR - USA - ABW currency: allOf: - title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR - description: Currency in which the order was placed. closedDate: description: 'Date on which order was closed after the product was shipped, paid for, and any refund period had elapsed.' type: string example: '2022-10-23T00:00:00Z' title: Date Time totalAmount: description: 'Total amount of the order, including tax, net of any discounts and refunds.' type: number format: decimal totalRefund: description: Total amount refunded issued by a merchant on an order (always a negative value). type: number format: decimal totalTaxAmount: description: Total amount of tax applied to the order. type: number format: decimal totalDiscount: description: Total amount of discount applied to the order. type: number format: decimal totalGratuity: description: Extra amount added to a bill. type: number format: decimal orderLineItems: type: array items: allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - properties: quantity: description: | Number of units of the product sold. For refunds, quantity is a negative value. type: number format: decimal taxPercentage: description: Percentage rate (from 0 to 100) of any sale tax applied to the unit amount. type: number format: decimal examples: - 0 - 12.5 - '45.00' totalAmount: description: 'Total price of the line item, including discounts, tax and minus any refunds.' type: number format: decimal totalTaxAmount: description: Total amount of tax applied to the line item. type: number format: decimal unitPrice: description: Price per unit of goods or service. type: number format: decimal taxes: description: Taxes breakdown as applied to order lines. type: array items: properties: taxComponentRef: description: Taxes rates reference object depending on the rates being available on source commerce package. type: object allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name rate: description: Tax amount on order line sale as available from source commerce platform. type: number format: decimal nullable: true productRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference that links the line item to the correct product details. productVariantRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference that links the line item to the specific version of product that has been ordered. discountAllocations: type: array items: type: object properties: name: description: Name of the discount in the commerce or point of sale platform. type: string example: Promotional Discount totalAmount: description: Total amount of discount applied. type: number format: decimal example: 15.25 payments: type: array items: type: object allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: amount: type: number nullable: true description: Payment Amount (including gratuity). examples: - 194.12 - -283.56 - 0 currency: description: Currency in which the payment was made. title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string format: ISO4217 examples: - GBP - USD - EUR type: type: string nullable: true description: Status of the payment enum: - Cash - Card - Invoice - OnlineCard - Swish - Vipps - Mobile - StoreCredit - Paypal - Custom - Prepaid - Unknown example: Cash status: type: string nullable: true description: Status of the payment enum: - Pending - Authorized - Paid - Failed - Cancelled - Unknown paymentProvider: type: string description: 'Service provider of the payment, if applicable.' examples: - Amazon Pay - Checkout.com - SagePay dueDate: description: Date by which payment must be made type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time serviceCharges: type: array items: type: object properties: description: description: Service charges for this order. type: string example: A service charge totalAmount: description: 'Total service charge, including taxes.' type: number format: decimal examples: - 0 - 12.5 - 45 taxPercentage: description: Percentage rate (from 0 to 100) of any tax applied to the service charge. type: number format: decimal examples: - 0 - 12.5 - 45 taxAmount: description: Amount of the service charge that is tax. type: number format: decimal examples: - 0 - 12.5 - 45 taxes: description: Taxes breakdown as applied to service charges. type: array items: properties: taxComponentRef: description: Taxes rates reference object depending on the rates being available on source commerce package. type: object allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name rate: description: Tax amount on order line sale as available from source commerce platform. type: number format: decimal nullable: true quantity: description: The number of times the charge is charged. type: number format: int examples: - 1 - 12 - 45 type: description: The type of the service charge. type: string enum: - Generic - Shipping - Overpayment - Unknown example: Overpayment locationRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference to the geographic location where the order was placed. customerRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference to the customer that placed the order. - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time definitions: lineItem: allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - properties: quantity: description: | Number of units of the product sold. For refunds, quantity is a negative value. type: number format: decimal taxPercentage: description: Percentage rate (from 0 to 100) of any sale tax applied to the unit amount. type: number format: decimal examples: - 0 - 12.5 - '45.00' totalAmount: description: 'Total price of the line item, including discounts, tax and minus any refunds.' type: number format: decimal totalTaxAmount: description: Total amount of tax applied to the line item. type: number format: decimal unitPrice: description: Price per unit of goods or service. type: number format: decimal taxes: description: Taxes breakdown as applied to order lines. type: array items: properties: taxComponentRef: description: Taxes rates reference object depending on the rates being available on source commerce package. type: object allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name rate: description: Tax amount on order line sale as available from source commerce platform. type: number format: decimal nullable: true productRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference that links the line item to the correct product details. productVariantRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference that links the line item to the specific version of product that has been ordered. discountAllocations: type: array items: type: object properties: name: description: Name of the discount in the commerce or point of sale platform. type: string example: Promotional Discount totalAmount: description: Total amount of discount applied. type: number format: decimal example: 15.25 paymentRef: type: object allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: amount: type: number nullable: true description: Payment Amount (including gratuity). examples: - 194.12 - -283.56 - 0 currency: description: Currency in which the payment was made. title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string format: ISO4217 examples: - GBP - USD - EUR type: type: string nullable: true description: Status of the payment enum: - Cash - Card - Invoice - OnlineCard - Swish - Vipps - Mobile - StoreCredit - Paypal - Custom - Prepaid - Unknown example: Cash status: type: string nullable: true description: Status of the payment enum: - Pending - Authorized - Paid - Failed - Cancelled - Unknown paymentProvider: type: string description: 'Service provider of the payment, if applicable.' examples: - Amazon Pay - Checkout.com - SagePay dueDate: description: Date by which payment must be made type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time serviceCharge: type: object properties: description: description: Service charges for this order. type: string example: A service charge totalAmount: description: 'Total service charge, including taxes.' type: number format: decimal examples: - 0 - 12.5 - 45 taxPercentage: description: Percentage rate (from 0 to 100) of any tax applied to the service charge. type: number format: decimal examples: - 0 - 12.5 - 45 taxAmount: description: Amount of the service charge that is tax. type: number format: decimal examples: - 0 - 12.5 - 45 taxes: description: Taxes breakdown as applied to service charges. type: array items: properties: taxComponentRef: description: Taxes rates reference object depending on the rates being available on source commerce package. type: object allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name rate: description: Tax amount on order line sale as available from source commerce platform. type: number format: decimal nullable: true quantity: description: The number of times the charge is charged. type: number format: int examples: - 1 - 12 - 45 type: description: The type of the service charge. type: string enum: - Generic - Shipping - Overpayment - Unknown example: Overpayment examples: - id: 01e63721-1205-478e-8503-9d8bf8a93f44 orderNumber: '99123956' country: CAN currency: CAD createdDate: '2021-03-28T03:00:14' totalAmount: 12 totalRefund: 0 totalTaxAmount: 2 totalDiscount: 0 totalGratuity: 1 orderLineItems: - id: 116113a6-54d3-4624-ba73-26a77a5ffd51 quantity: 1 taxPercentage: 20 totalAmount: 12 totalTaxAmount: 2 unitPrice: 10 taxes: - taxComponentRef: id: '72' name: Sales Tax taxAmount: '' - taxComponentRef: id: '72' name: City Tax taxAmount: '' productRef: id: ac186646-41f2-4280-afea-1012c59459ab name: Intelligent Concrete Salad productVariantRef: id: f9ca9de5-9e31-460d-ac81-368f4e7c8fc0 name: Small Incredible Wooden Soap discountAllocations: [] payments: - id: defdceb6-83a3-4b7d-a74e-e9ef947d5f48 amount: 12 currency: CAD type: Paypal status: Unknown dueDate: '2021-04-04T03:00:14' createdDate: '2021-03-28T03:00:14' modifiedDate: '2022-02-02T11:02:45' serviceCharges: - description: Service Charge totalAmount: 1.2 taxPercentage: 20 taxAmount: 0.2 taxes: - taxComponentRef: id: '72' name: Service Tax taxAmount: '' quantity: 1 type: Generic locationRef: id: 47bbffc7-c045-4b0f-a3bb-ecf1f669edfa customerRef: id: 2634d180-7205-43f0-a73d-84af6443a005 name: Emmy Roberts modifiedDate: '2022-02-02T11:02:45Z' sourceModifiedDate: '2021-03-28T03:00:14' - type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: type: object x-internal: true required: - self - current properties: self: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference current: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference next: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference previous: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' operationId: list-commerce-orders description: Get a list of orders placed or held on the linked commerce platform parameters: - name: page in: query required: true schema: type: integer format: int32 minimum: 0 example: 1 default: 1 description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: 1318joqblpp4e - name: pageSize in: query schema: type: integer format: int32 default: 100 example: 100 minimum: 1 maximum: 5000 description: 'Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: s2ika6rltk5y6 - name: query in: query required: false schema: type: string description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).' x-stoplight: id: gupdb9kt30hfq - name: orderBy in: query required: false schema: type: string example: '-modifiedDate' description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).' x-stoplight: id: 4je9lwo02netu '/companies/{companyId}/connections/{connectionId}/data/commerce-payments': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: List payments tags: - Payments responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: results: type: array items: title: Payment description: A payment made in a commerce platform x-stoplight: id: wcffh3qwn0c3z x-datatype: dataTypeId: 92c83841-a935-43af-a134-48bae6dbf72d databaseId: 32 name: commerce-payments domain: commerce singluar: payments plural: payment fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: amount: type: number description: Payment Amount (including gratuity) examples: - 194.12 - -283.56 - 0 currency: description: Currency in which the payment was made title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string format: ISO4217 examples: - GBP - USD - EUR paymentMethodRef: description: The payment method the payment is linked to in the commerce platform. example: id: EILBDVJVNUAGVKRQ name: AliPay title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name status: type: string description: Status of the payment enum: - Pending - Authorized - Paid - Failed - Cancelled - Unknown paymentProvider: type: string description: 'Service provider of the payment, if applicable.' examples: - Amazon Pay - Checkout.com - SagePay dueDate: description: Date by which payment must be made type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: type: object x-internal: true required: - self - current properties: self: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference current: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference next: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference previous: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' operationId: list-commerce-payments description: List commerce payments for the given company & data connection. parameters: - name: page in: query required: true schema: type: integer format: int32 minimum: 0 example: 1 default: 1 description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: 1318joqblpp4e - name: pageSize in: query schema: type: integer format: int32 default: 100 example: 100 minimum: 1 maximum: 5000 description: 'Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: s2ika6rltk5y6 - name: query in: query required: false schema: type: string description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).' x-stoplight: id: gupdb9kt30hfq - name: orderBy in: query required: false schema: type: string example: '-modifiedDate' description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).' x-stoplight: id: 4je9lwo02netu '/companies/{companyId}/connections/{connectionId}/data/commerce-paymentMethods': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: List payment methods tags: - Payments responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: results: type: array items: title: Payment Method x-stoplight: id: ivpv6516qf630 type: object x-datatype: id: 2ed4946e-a548-4ffb-931c-963511372943 databaseId: 41 name: commerce-paymentMethods domain: commerce singluar: payment method plural: payment methods fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: name: type: string description: The name of the PaymentMethod example: Alipay status: type: string enum: - Active - Archived - Unknown description: Status of the Payment Method example: Active allOf: - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: type: object x-internal: true required: - self - current properties: self: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference current: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference next: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference previous: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' operationId: list-commerce-paymentMethods description: 'Retrieve a list of payment methods, such as card, cash or other online payment methods, as held in the linked commerce platform.' parameters: - name: page in: query required: true schema: type: integer format: int32 minimum: 0 example: 1 default: 1 description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: 1318joqblpp4e - name: pageSize in: query schema: type: integer format: int32 default: 100 example: 100 minimum: 1 maximum: 5000 description: 'Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: s2ika6rltk5y6 - name: query in: query required: false schema: type: string description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).' x-stoplight: id: gupdb9kt30hfq - name: orderBy in: query required: false schema: type: string example: '-modifiedDate' description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).' x-stoplight: id: 4je9lwo02netu '/companies/{companyId}/connections/{connectionId}/data/commerce-products': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: List products tags: - Products responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: results: type: array items: $id: 'https://schemas.codat.io/datamodel/commerce/product.json' title: Product description: | A Product is an item in the company's inventory, and includes information about the price and quantity of all products, and variants thereof, available for sale x-stoplight: id: egcimxah1hg79 type: object x-datatype: dataTypeId: fb247940-3367-4e95-a689-069c10354a3d databaseId: 23 name: commerce-products domain: commerce singluar: product plural: products fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: name: type: string description: Name of the product in the commerce or POS system examples: - Hard Drive - Windows Installation - Software Support (Hourly) description: type: string description: Description of the product recorded in the commerce or point of sale platform. examples: - 1tb Western Digital Hard Drive - Install of Windows 11 (Professional Edition) - 1 hour of support from an agent (phone or remote) categorization: type: string description: Retail category that the product is assigned to examples: - Hardware - Software - Support Services isGiftCard: type: boolean description: | Whether the product represents a gift card or voucher that can be redeemed in the commerce or POS platform variants: type: array items: title: Product Variant description: | Represents a variation of a product available for sale, for example an item of clothing may be available for sale in multiple sizes and colors x-stoplight: id: z8pyy073x77y2 type: object allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - properties: name: type: string examples: - Red Coat - Black Coat - Large Brown Hat quantity: type: number format: decimal examples: - 0 - 10 - 100.54 isTaxEnabled: type: boolean sku: type: string examples: - Coat-Red-Lrg - Coat-Black-Md - LargeBrownHat - A725BA2 barcode: type: string examples: - '564158468416486458646886484' - CSE370 unitOfMeasure: type: string examples: - kg - m - meters vatPercentage: type: number format: decimal examples: - 12.5 - 0 - 20 prices: type: array items: properties: unitPrice: type: number format: decimal currency: title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR inventory: type: array items: properties: totalQuantity: type: number format: decimal example: 1 locations: type: array items: properties: quantity: type: number format: decimal example: 1 locationRef: title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name shippingRequired: type: boolean status: type: string enum: - Unknown - Published - Unpublished - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: type: object x-internal: true required: - self - current properties: self: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference current: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference next: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference previous: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' operationId: list-commerce-products parameters: - name: page in: query required: true schema: type: integer format: int32 minimum: 0 example: 1 default: 1 description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: 1318joqblpp4e - name: pageSize in: query schema: type: integer format: int32 default: 100 example: 100 minimum: 1 maximum: 5000 description: 'Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: s2ika6rltk5y6 - name: query in: query required: false schema: type: string description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).' x-stoplight: id: gupdb9kt30hfq - name: orderBy in: query required: false schema: type: string example: '-modifiedDate' description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).' x-stoplight: id: 4je9lwo02netu description: 'The Products data type provides the company''s product inventory, and includes the price and quantity of all products, and product variants, available for sale.' '/companies/{companyId}/connections/{connectionId}/data/commerce-transactions': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: List transactions tags: - Transactions responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: results: type: array items: title: Transaction description: A financial transaction recorded in the commerce or point of sale system x-stoplight: id: z40cc0atpg1x9 x-datatype: dataTypeId: 49f67a7d-d196-489d-a7dc-7f834d3f1a68 databaseId: 26 name: commerce-transactions domain: commerce singluar: transaction plural: transactions fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: totalAmount: description: The total transaction amount type: number examples: - 194.12 - -283.56 - 0 currency: title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR type: description: The type of the platform transaction type: string enum: - Payment - Refund - Payout - FailedPayout - Transfer - PaymentFee - PaymentFeeRefund - Unknown subType: description: Non-standardised transaction type data from the commerce platform type: string examples: - CardPayment - Invoice payment transactionSourceRef: description: Link to the source event which triggered this transaction allOf: - title: TransactionSourceRef x-stoplight: id: ydj5jokox9hvp type: object allOf: - title: Record Ref x-internal: true type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ type: description: The type of record being referenced. type: string required: - id - type description: '' - properties: type: enum: - Fee - Order - Payment - ServiceCharge - Unknown - allOf: - type: object x-stoplight: id: c590b4405180f allOf: - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-stoplight: id: gdyjg7bg783br properties: sourceCreatedDate: description: The date on which this record was created in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time x-stoplight: id: 9e815c1766554 - type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: type: object x-internal: true required: - self - current properties: self: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference current: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference next: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference previous: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' operationId: list-commerce-transactions description: 'Details of all financial transactions recorded in the commerce or point of sale system are added to the Transactions data type. For example, payments, service charges, and fees.' parameters: - name: page in: query required: true schema: type: integer format: int32 minimum: 0 example: 1 default: 1 description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: 1318joqblpp4e - name: pageSize in: query schema: type: integer format: int32 default: 100 example: 100 minimum: 1 maximum: 5000 description: 'Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: s2ika6rltk5y6 - name: query in: query required: false schema: type: string description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).' x-stoplight: id: gupdb9kt30hfq - name: orderBy in: query required: false schema: type: string example: '-modifiedDate' description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).' x-stoplight: id: 4je9lwo02netu '/companies/{companyId}/connections/{connectionId}/data/commerce-productCategories': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: List product categories tags: - Products responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: results: type: array items: type: object x-examples: example-1: id: '100' name: Entertainment ancestorRefs: [] hasChildren: true modifiedDate: '2022-01-01T12:00:00Z' sourceModifiedDate: '2021-10-01T12:53:21Z' properties: id: type: string example: '"102"' name: type: string example: Entertainment ancestorRefs: type: array items: title: Record Ref x-internal: true type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ type: description: The type of record being referenced. type: string required: - id - type description: '' hasChildren: type: boolean modifiedDate: title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time sourceModifiedDate: title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time title: Product Category description: 'Product categories are used to classify a group of products together, either by type (eg "Furniture"), or sometimes by tax profile.' - type: object x-internal: true properties: pageNumber: type: integer pageSize: type: integer totalResults: type: integer _links: type: object x-internal: true required: - self - current properties: self: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference current: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference next: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference previous: title: Hypertext reference type: object x-internal: true properties: href: type: string format: uri-reference examples: - self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' required: - pageNumber - pageSize - totalResults - _links examples: - _links: pageNumber: 1 pageSize: 10 totalResults: 1 self: href: '/companies/{id}/data/{dataType}' current: href: '/companies/{id}/data/{dataType}?page=1&pageSize=10' operationId: list-commerce-productCategories parameters: - name: page in: query required: true schema: type: integer format: int32 minimum: 0 example: 1 default: 1 description: 'Page number. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: 1318joqblpp4e - name: pageSize in: query schema: type: integer format: int32 default: 100 example: 100 minimum: 1 maximum: 5000 description: 'Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).' x-stoplight: id: s2ika6rltk5y6 - name: query in: query required: false schema: type: string description: 'Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).' x-stoplight: id: gupdb9kt30hfq - name: orderBy in: query required: false schema: type: string example: '-modifiedDate' description: 'Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).' x-stoplight: id: 4je9lwo02netu description: 'Product categories are used to classify a group of products together, either by type (eg "Furniture"), or sometimes by tax profile.' '/companies/{companyId}/connections/{connectionId}/data/commerce-taxComponents': parameters: - name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. - name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. x-stoplight: id: odjhmld3g3nmi get: summary: List tax components tags: - Tax components responses: '200': description: OK content: application/json: schema: type: object properties: taxComponents: type: array items: title: Tax Component x-stoplight: id: uor9593ahnu9j type: object x-datatype: id: 72715173-20e5-40b5-a825-378ab8195d28 databaseId: 42 name: commerce-taxComponents domain: commerce singluar: tax component plural: tax components fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: name: type: string description: Name of the Tax Rate Component in the source commerce platform. example: Sales Tax rate: description: Rate of taxation represented as a fraction of the net price (typically in the range 0.00 - 1.00). type: number format: float examples: - 0.15 - 0.2 isCompound: description: The Boolean flag to indicate when a Tax Rate Component compounds on a sale. type: boolean examples: - true - false allOf: - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time required: - name definitions: taxComponentAllocation: properties: taxComponentRef: description: Taxes rates reference object depending on the rates being available on source commerce package. type: object allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name rate: description: Tax amount on order line sale as available from source commerce platform. type: number format: decimal nullable: true description: '' examples: - id: 13d946f0-c5d5-42bc-b092-97ece17923ab name: Sales Tax (15%) rate: 0.15 isCompound: true modifiedDate: '2022-10-23T00:00:00Z' sourceModifiedDate: '2022-10-23T00:00:00Z' examples: Example 1: value: taxComponents: - id: 85b32439-37a0-4085-b710-054732bbcea2 name: Sales Tax (10%) rate: 0.1 isCompound: false modifiedDate: '2021-08-06T06:00:27' sourceModifiedDate: '2021-08-06T06:00:27' - id: 687e67ae-80f2-44e0-b17a-6a3e1f9c00f9 name: Sales Tax (15%) rate: 0.15 isCompound: false modifiedDate: '2021-08-06T06:00:27' sourceModifiedDate: '2022-04-25T02:45:27' operationId: get-companies-companyId-connections-connectionId-data-commerce-taxComponents description: 'This endpoint returns a lits of tax rates from the commerce platform, including tax rate names and values. This supports the mapping of tax rates from the commerce platform to the accounting platform.' components: schemas: CompanyInfo: title: Company Info description: | In the Codat system, company information includes standard commercial details about a linked company, such as their address, phone number, and company registration. x-stoplight: id: d7on55ll1hvqj type: object x-datatype: dataTypeId: d68f4a5e-f1f8-40f0-a28d-565ef0733fb1 databaseId: 33 name: commerce-companyInfo domain: commerce singluar: company infomation plural: company infomation fetchMode: single properties: companyName: type: string description: The name of the company example: Codat commercePlatformRef: type: string description: Identifier or reference for the company in the commerce platform companyLegalName: type: string description: The full legal name of the company example: Codat Limited addresses: type: array description: Addresses associated with the company items: allOf: - title: Address x-stoplight: id: lih0rzmqm2onw type: object properties: type: description: The type of the address type: string enum: - Billing - Delivery - Order - Inventory - Unknown line1: description: The first line of the address type: string line2: description: The second line of the address type: string city: description: 'The third line of the address, or city' type: string region: description: 'The fourth line of the address, or region' type: string country: description: The country for the address type: string postalCode: description: The postal (or zip) code for the address type: string - properties: type: enum: - Billing - Delivery phoneNumbers: type: array description: Phone numbers associated with the company items: type: object properties: number: title: Phone Number x-stoplight: id: 1ch48ghi554eb type: string description: A phone number examples: - +44 25691 154789 - (877) 492-8687 - 01224 658 999 type: description: The type of phone number type: string enum: - Primary - Landline - Mobile - Fax - Unknown required: - number - type webLinks: description: Web links associated with the company type: array items: properties: type: description: The type of the weblink type: string enum: - Website - Social - Unknown url: description: The full URL for the weblink type: string format: url example: type: Website url: 'https://codat.io' registrationNumber: description: The registration number of the company type: string examples: - 10480375 baseCurrency: title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR accountBalances: description: The available and current cash balances for the company's accounts type: array items: type: object properties: available: description: The account's current balance type: number format: decimal pending: description: Funds that are not yet available in the balance type: number format: decimal reserved: description: Funds reserved as holdings type: number format: decimal currency: description: The currency of the account allOf: - title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR sourceUrls: description: 'URL addresses for the originating system. For example, potential use cases include ''deeplinking'' to the originating system' type: object additionalProperties: type: string example: url1: 'https://connect.sandbox.com/v2/customers' url2: 'https://connect.sandbox.com/v2/disputes' allOf: - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time Customer: $id: 'https://schemas.codat.io/datamodel/commerce/customer.json' title: Customer description: Represents a customer who has placed an order in the commerce system" x-stoplight: id: avuh8zncanxa4 type: object x-datatype: dataTypeId: f51d742e-6797-4ae0-8b3c-63cc6c9d1972 databaseId: 24 name: commerce-customers domain: commerce singluar: customer plural: customers fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: customerName: type: string description: Name of the customer example: Fred Smith emailAddress: type: string description: Email address of the customer example: fred.smith@myCompany.com phone: title: Phone Number x-stoplight: id: 1ch48ghi554eb type: string description: A phone number examples: - +44 25691 154789 - (877) 492-8687 - 01224 658 999 defaultCurrency: allOf: - description: | Default currency of any transactional data for the customer, for example, orders or payments - title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR addresses: type: array description: Addresses of the customer items: allOf: - title: Address x-stoplight: id: lih0rzmqm2onw type: object properties: type: description: The type of the address type: string enum: - Billing - Delivery - Order - Inventory - Unknown line1: description: The first line of the address type: string line2: description: The second line of the address type: string city: description: 'The third line of the address, or city' type: string region: description: 'The fourth line of the address, or region' type: string country: description: The country for the address type: string postalCode: description: The postal (or zip) code for the address type: string - properties: type: enum: - Billing - Delivery note: type: string description: Any additional information about the customer - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time Dispute: title: Dispute x-stoplight: id: ivpv6516qf630 type: object x-datatype: id: cf7f81a2-13a7-4f63-8862-604dd7bdfd2a databaseId: 25 name: commerce-disputes domain: commerce singluar: dispute plural: disputes fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: disputedTransactions: description: Link to the source event which triggered this transaction. allOf: - title: TransactionSourceRef x-stoplight: id: ydj5jokox9hvp type: object allOf: - title: Record Ref x-internal: true type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ type: description: The type of record being referenced. type: string required: - id - type description: '' - properties: type: enum: - Fee - Order - Payment - ServiceCharge - Unknown totalAmount: description: Total transaction amount that is under dispute. type: number examples: - 194.12 - -283.56 - 0 currency: description: Currency of the disputed transaction. title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string format: ISO4217 examples: - GBP - USD - EUR status: description: Current status of the dispute type: string enum: - Won - Lost - Accepted - Processing - ChargeRefunded - EvidenceRequired - InquiryEvidenceRequired - InquiryProcessing - InquiryClosed - WaitingThirdParty - Unknown example: EvidenceRequired reason: description: Reason for the dispute type: string examples: - Unhappy with product dueDate: description: Date when the next action in the dispute resolution is due type: string example: '2022-10-23T00:00:00Z' title: Date Time allOf: - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time required: - currency Locations: title: Locations x-stoplight: id: 2d4g3i124e1ea type: object x-datatype: dataTypeId: 6fe79975-e07b-45ba-b878-25329dddd94a databaseId: 34 name: commerce-locations domain: commerce singluar: location plural: locations fetchMode: multiple description: | The Locations datatype holds information on geographic locations at which stocks of products may be held, as referenced in the Products data type. Locations also holds information on geographic locations where orders were placed, as referenced in the Orders data type. From the Locations endpoints you can retrieve: A list of all the Locations of a commerce company: `GET /companies/{companyId}/connections/{connectionId}/data/commerce-locations`. The details of an individual location: `GET /companies/{companyId}/connections/{connectionId}/data/commerce-locations/{locationId}`. allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: name: description: Name of this location type: string address: description: Address associated with the location allOf: - title: Address x-stoplight: id: lih0rzmqm2onw type: object properties: type: description: The type of the address type: string enum: - Billing - Delivery - Order - Inventory - Unknown line1: description: The first line of the address type: string line2: description: The second line of the address type: string city: description: 'The third line of the address, or city' type: string region: description: 'The fourth line of the address, or region' type: string country: description: The country for the address type: string postalCode: description: The postal (or zip) code for the address type: string - properties: type: enum: - Billing - Delivery - Inventory - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time Order: title: Orders x-stoplight: id: bg1uwd537qhia type: object x-datatype: dataTypeId: 6e57c403-248d-4851-96fb-d7c903cd8929 databaseId: 22 name: commerce-orders domain: commerce singluar: order plural: orders fetchMode: multiple description: | Orders contain the transaction details for all products sold by the company, and include details of any payments, service charges, or refunds related to each order. From the Orders endpoints you can retrieve: A list of all the orders for a commerce company: `GET /companies/{companyId}/connections/{connectionId}/data/commerce-orders`. The details of an individual order: `GET /companies/{companyId}/connections/{connectionId}/data/commerce-orders/{orderId}`. Note that for refunds `quantity` is a negative value and `unitPrice` is a positive value. allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - properties: orderNumber: type: string description: Friendly reference for the order in the commerce or point of sale platform. country: description: |- The Codat country property is returned as it was provided in the underlying platform by the company without any formatting on our part. Depending on the platform the value of this property will either be an ISO 3166 code (2-alpha or 3-alpha) or free-form text returned as a string name in our model. For POST operations against platforms that demand a specific format for the country code, we have documented accepted values in the [options](https://docs.codat.io/codat-api#/operations/get-companies-companyId-connections-connectionId-push) endpoint. type: string format: ISO3166 Alpha-3 examples: - GBR - USA - ABW currency: allOf: - title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR - description: Currency in which the order was placed. closedDate: description: 'Date on which order was closed after the product was shipped, paid for, and any refund period had elapsed.' type: string example: '2022-10-23T00:00:00Z' title: Date Time totalAmount: description: 'Total amount of the order, including tax, net of any discounts and refunds.' type: number format: decimal totalRefund: description: Total amount refunded issued by a merchant on an order (always a negative value). type: number format: decimal totalTaxAmount: description: Total amount of tax applied to the order. type: number format: decimal totalDiscount: description: Total amount of discount applied to the order. type: number format: decimal totalGratuity: description: Extra amount added to a bill. type: number format: decimal orderLineItems: type: array items: allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - properties: quantity: description: | Number of units of the product sold. For refunds, quantity is a negative value. type: number format: decimal taxPercentage: description: Percentage rate (from 0 to 100) of any sale tax applied to the unit amount. type: number format: decimal examples: - 0 - 12.5 - '45.00' totalAmount: description: 'Total price of the line item, including discounts, tax and minus any refunds.' type: number format: decimal totalTaxAmount: description: Total amount of tax applied to the line item. type: number format: decimal unitPrice: description: Price per unit of goods or service. type: number format: decimal taxes: description: Taxes breakdown as applied to order lines. type: array items: properties: taxComponentRef: description: Taxes rates reference object depending on the rates being available on source commerce package. type: object allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name rate: description: Tax amount on order line sale as available from source commerce platform. type: number format: decimal nullable: true productRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference that links the line item to the correct product details. productVariantRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference that links the line item to the specific version of product that has been ordered. discountAllocations: type: array items: type: object properties: name: description: Name of the discount in the commerce or point of sale platform. type: string example: Promotional Discount totalAmount: description: Total amount of discount applied. type: number format: decimal example: 15.25 payments: type: array items: type: object allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: amount: type: number nullable: true description: Payment Amount (including gratuity). examples: - 194.12 - -283.56 - 0 currency: description: Currency in which the payment was made. title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string format: ISO4217 examples: - GBP - USD - EUR type: type: string nullable: true description: Status of the payment enum: - Cash - Card - Invoice - OnlineCard - Swish - Vipps - Mobile - StoreCredit - Paypal - Custom - Prepaid - Unknown example: Cash status: type: string nullable: true description: Status of the payment enum: - Pending - Authorized - Paid - Failed - Cancelled - Unknown paymentProvider: type: string description: 'Service provider of the payment, if applicable.' examples: - Amazon Pay - Checkout.com - SagePay dueDate: description: Date by which payment must be made type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time serviceCharges: type: array items: type: object properties: description: description: Service charges for this order. type: string example: A service charge totalAmount: description: 'Total service charge, including taxes.' type: number format: decimal examples: - 0 - 12.5 - 45 taxPercentage: description: Percentage rate (from 0 to 100) of any tax applied to the service charge. type: number format: decimal examples: - 0 - 12.5 - 45 taxAmount: description: Amount of the service charge that is tax. type: number format: decimal examples: - 0 - 12.5 - 45 taxes: description: Taxes breakdown as applied to service charges. type: array items: properties: taxComponentRef: description: Taxes rates reference object depending on the rates being available on source commerce package. type: object allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name rate: description: Tax amount on order line sale as available from source commerce platform. type: number format: decimal nullable: true quantity: description: The number of times the charge is charged. type: number format: int examples: - 1 - 12 - 45 type: description: The type of the service charge. type: string enum: - Generic - Shipping - Overpayment - Unknown example: Overpayment locationRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference to the geographic location where the order was placed. customerRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference to the customer that placed the order. - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time definitions: lineItem: allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - properties: quantity: description: | Number of units of the product sold. For refunds, quantity is a negative value. type: number format: decimal taxPercentage: description: Percentage rate (from 0 to 100) of any sale tax applied to the unit amount. type: number format: decimal examples: - 0 - 12.5 - '45.00' totalAmount: description: 'Total price of the line item, including discounts, tax and minus any refunds.' type: number format: decimal totalTaxAmount: description: Total amount of tax applied to the line item. type: number format: decimal unitPrice: description: Price per unit of goods or service. type: number format: decimal taxes: description: Taxes breakdown as applied to order lines. type: array items: properties: taxComponentRef: description: Taxes rates reference object depending on the rates being available on source commerce package. type: object allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name rate: description: Tax amount on order line sale as available from source commerce platform. type: number format: decimal nullable: true productRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference that links the line item to the correct product details. productVariantRef: allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name - description: Reference that links the line item to the specific version of product that has been ordered. discountAllocations: type: array items: type: object properties: name: description: Name of the discount in the commerce or point of sale platform. type: string example: Promotional Discount totalAmount: description: Total amount of discount applied. type: number format: decimal example: 15.25 paymentRef: type: object allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: amount: type: number nullable: true description: Payment Amount (including gratuity). examples: - 194.12 - -283.56 - 0 currency: description: Currency in which the payment was made. title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string format: ISO4217 examples: - GBP - USD - EUR type: type: string nullable: true description: Status of the payment enum: - Cash - Card - Invoice - OnlineCard - Swish - Vipps - Mobile - StoreCredit - Paypal - Custom - Prepaid - Unknown example: Cash status: type: string nullable: true description: Status of the payment enum: - Pending - Authorized - Paid - Failed - Cancelled - Unknown paymentProvider: type: string description: 'Service provider of the payment, if applicable.' examples: - Amazon Pay - Checkout.com - SagePay dueDate: description: Date by which payment must be made type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time serviceCharge: type: object properties: description: description: Service charges for this order. type: string example: A service charge totalAmount: description: 'Total service charge, including taxes.' type: number format: decimal examples: - 0 - 12.5 - 45 taxPercentage: description: Percentage rate (from 0 to 100) of any tax applied to the service charge. type: number format: decimal examples: - 0 - 12.5 - 45 taxAmount: description: Amount of the service charge that is tax. type: number format: decimal examples: - 0 - 12.5 - 45 taxes: description: Taxes breakdown as applied to service charges. type: array items: properties: taxComponentRef: description: Taxes rates reference object depending on the rates being available on source commerce package. type: object allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name rate: description: Tax amount on order line sale as available from source commerce platform. type: number format: decimal nullable: true quantity: description: The number of times the charge is charged. type: number format: int examples: - 1 - 12 - 45 type: description: The type of the service charge. type: string enum: - Generic - Shipping - Overpayment - Unknown example: Overpayment examples: - id: 01e63721-1205-478e-8503-9d8bf8a93f44 orderNumber: '99123956' country: CAN currency: CAD createdDate: '2021-03-28T03:00:14' totalAmount: 12 totalRefund: 0 totalTaxAmount: 2 totalDiscount: 0 totalGratuity: 1 orderLineItems: - id: 116113a6-54d3-4624-ba73-26a77a5ffd51 quantity: 1 taxPercentage: 20 totalAmount: 12 totalTaxAmount: 2 unitPrice: 10 taxes: - taxComponentRef: id: '72' name: Sales Tax taxAmount: '' - taxComponentRef: id: '72' name: City Tax taxAmount: '' productRef: id: ac186646-41f2-4280-afea-1012c59459ab name: Intelligent Concrete Salad productVariantRef: id: f9ca9de5-9e31-460d-ac81-368f4e7c8fc0 name: Small Incredible Wooden Soap discountAllocations: [] payments: - id: defdceb6-83a3-4b7d-a74e-e9ef947d5f48 amount: 12 currency: CAD type: Paypal status: Unknown dueDate: '2021-04-04T03:00:14' createdDate: '2021-03-28T03:00:14' modifiedDate: '2022-02-02T11:02:45' serviceCharges: - description: Service Charge totalAmount: 1.2 taxPercentage: 20 taxAmount: 0.2 taxes: - taxComponentRef: id: '72' name: Service Tax taxAmount: '' quantity: 1 type: Generic locationRef: id: 47bbffc7-c045-4b0f-a3bb-ecf1f669edfa customerRef: id: 2634d180-7205-43f0-a73d-84af6443a005 name: Emmy Roberts modifiedDate: '2022-02-02T11:02:45Z' sourceModifiedDate: '2021-03-28T03:00:14' Payment: title: Payment description: A payment made in a commerce platform x-stoplight: id: wcffh3qwn0c3z x-datatype: dataTypeId: 92c83841-a935-43af-a134-48bae6dbf72d databaseId: 32 name: commerce-payments domain: commerce singluar: payments plural: payment fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: amount: type: number description: Payment Amount (including gratuity) examples: - 194.12 - -283.56 - 0 currency: description: Currency in which the payment was made title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string format: ISO4217 examples: - GBP - USD - EUR paymentMethodRef: description: The payment method the payment is linked to in the commerce platform. example: id: EILBDVJVNUAGVKRQ name: AliPay title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name status: type: string description: Status of the payment enum: - Pending - Authorized - Paid - Failed - Cancelled - Unknown paymentProvider: type: string description: 'Service provider of the payment, if applicable.' examples: - Amazon Pay - Checkout.com - SagePay dueDate: description: Date by which payment must be made type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time PaymentMethod: title: Payment Method x-stoplight: id: ivpv6516qf630 type: object x-datatype: id: 2ed4946e-a548-4ffb-931c-963511372943 databaseId: 41 name: commerce-paymentMethods domain: commerce singluar: payment method plural: payment methods fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: name: type: string description: The name of the PaymentMethod example: Alipay status: type: string enum: - Active - Archived - Unknown description: Status of the Payment Method example: Active allOf: - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time Product: $id: 'https://schemas.codat.io/datamodel/commerce/product.json' title: Product description: | A Product is an item in the company's inventory, and includes information about the price and quantity of all products, and variants thereof, available for sale x-stoplight: id: egcimxah1hg79 type: object x-datatype: dataTypeId: fb247940-3367-4e95-a689-069c10354a3d databaseId: 23 name: commerce-products domain: commerce singluar: product plural: products fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: name: type: string description: Name of the product in the commerce or POS system examples: - Hard Drive - Windows Installation - Software Support (Hourly) description: type: string description: Description of the product recorded in the commerce or point of sale platform. examples: - 1tb Western Digital Hard Drive - Install of Windows 11 (Professional Edition) - 1 hour of support from an agent (phone or remote) categorization: type: string description: Retail category that the product is assigned to examples: - Hardware - Software - Support Services isGiftCard: type: boolean description: | Whether the product represents a gift card or voucher that can be redeemed in the commerce or POS platform variants: type: array items: title: Product Variant description: | Represents a variation of a product available for sale, for example an item of clothing may be available for sale in multiple sizes and colors x-stoplight: id: z8pyy073x77y2 type: object allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - properties: name: type: string examples: - Red Coat - Black Coat - Large Brown Hat quantity: type: number format: decimal examples: - 0 - 10 - 100.54 isTaxEnabled: type: boolean sku: type: string examples: - Coat-Red-Lrg - Coat-Black-Md - LargeBrownHat - A725BA2 barcode: type: string examples: - '564158468416486458646886484' - CSE370 unitOfMeasure: type: string examples: - kg - m - meters vatPercentage: type: number format: decimal examples: - 12.5 - 0 - 20 prices: type: array items: properties: unitPrice: type: number format: decimal currency: title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR inventory: type: array items: properties: totalQuantity: type: number format: decimal example: 1 locations: type: array items: properties: quantity: type: number format: decimal example: 1 locationRef: title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name shippingRequired: type: boolean status: type: string enum: - Unknown - Published - Unpublished - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time ProductCategory: type: object x-examples: example-1: id: '100' name: Entertainment ancestorRefs: [] hasChildren: true modifiedDate: '2022-01-01T12:00:00Z' sourceModifiedDate: '2021-10-01T12:53:21Z' properties: id: type: string example: '"102"' name: type: string example: Entertainment ancestorRefs: type: array items: title: Record Ref x-internal: true type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ type: description: The type of record being referenced. type: string required: - id - type description: '' hasChildren: type: boolean modifiedDate: title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time sourceModifiedDate: title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time title: Product Category description: 'Product categories are used to classify a group of products together, either by type (eg "Furniture"), or sometimes by tax profile.' TaxComponent: title: Tax Component x-stoplight: id: uor9593ahnu9j type: object x-datatype: id: 72715173-20e5-40b5-a825-378ab8195d28 databaseId: 42 name: commerce-taxComponents domain: commerce singluar: tax component plural: tax components fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: name: type: string description: Name of the Tax Rate Component in the source commerce platform. example: Sales Tax rate: description: Rate of taxation represented as a fraction of the net price (typically in the range 0.00 - 1.00). type: number format: float examples: - 0.15 - 0.2 isCompound: description: The Boolean flag to indicate when a Tax Rate Component compounds on a sale. type: boolean examples: - true - false allOf: - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time required: - name definitions: taxComponentAllocation: properties: taxComponentRef: description: Taxes rates reference object depending on the rates being available on source commerce package. type: object allOf: - title: nameRef x-stoplight: id: 34dd919grzbls type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ name: description: Name of the record being referenced. type: string required: - id - name rate: description: Tax amount on order line sale as available from source commerce platform. type: number format: decimal nullable: true description: '' examples: - id: 13d946f0-c5d5-42bc-b092-97ece17923ab name: Sales Tax (15%) rate: 0.15 isCompound: true modifiedDate: '2022-10-23T00:00:00Z' sourceModifiedDate: '2022-10-23T00:00:00Z' Transaction: title: Transaction description: A financial transaction recorded in the commerce or point of sale system x-stoplight: id: z40cc0atpg1x9 x-datatype: dataTypeId: 49f67a7d-d196-489d-a7dc-7f834d3f1a68 databaseId: 26 name: commerce-transactions domain: commerce singluar: transaction plural: transactions fetchMode: multiple allOf: - type: object x-stoplight: id: 516bf0ecc4907 required: - id properties: id: type: string description: 'A unique, persistent identifier for this record' examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ x-codat-validation: - validator: UniqueWithinConnection - type: object properties: totalAmount: description: The total transaction amount type: number examples: - 194.12 - -283.56 - 0 currency: title: Currency x-stoplight: id: 8ljuulqyuc5l4 type: string description: |- The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. e.g. _GBP_. ## Unknown currencies In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction. There are only a very small number of edge cases where this currency code is returned by the Codat system. format: ISO4217 examples: - GBP - USD - EUR type: description: The type of the platform transaction type: string enum: - Payment - Refund - Payout - FailedPayout - Transfer - PaymentFee - PaymentFeeRefund - Unknown subType: description: Non-standardised transaction type data from the commerce platform type: string examples: - CardPayment - Invoice payment transactionSourceRef: description: Link to the source event which triggered this transaction allOf: - title: TransactionSourceRef x-stoplight: id: ydj5jokox9hvp type: object allOf: - title: Record Ref x-internal: true type: object properties: id: description: The unique identitifer of the record being referenced type: string examples: - 13d946f0-c5d5-42bc-b092-97ece17923ab - 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2 - 7110701885 - EILBDVJVNUAGVKRQ type: description: The type of record being referenced. type: string required: - id - type description: '' - properties: type: enum: - Fee - Order - Payment - ServiceCharge - Unknown - allOf: - type: object x-stoplight: id: c590b4405180f allOf: - type: object x-stoplight: id: yptfg1r7vj69j properties: createdDate: description: The date the entity was created. type: string example: '2022-10-23T00:00:00Z' title: Date Time - type: object x-stoplight: id: gdyjg7bg783br properties: sourceCreatedDate: description: The date on which this record was created in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time - allOf: - title: ModifiedDate x-stoplight: id: z5gfpfg4fsp6v type: object properties: modifiedDate: description: The date on which this record was last modified in Codat. type: string example: '2022-10-23T00:00:00Z' title: Date Time - title: SourceModifiedDate x-stoplight: id: s0oihleme8suj type: object properties: sourceModifiedDate: description: The date on which this record was last modified in the originating system type: string example: '2022-10-23T00:00:00Z' title: Date Time x-stoplight: id: 9e815c1766554 securitySchemes: auth_header: name: Authorization description: 'The word "Basic" followed by a space and your API Key, base64 encoded, which can be found [here](https://app.codat.io/developers/api-keys)' type: apiKey in: header