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:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List customers
tags:
- Customers
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Customers'
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-customers
description: List all commerce customers for the given company and data connection
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
'/companies/{companyId}/connections/{connectionId}/data/commerce-disputes':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List disputes
tags:
- Disputes
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Disputes'
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-disputes
description: List commerce disputes
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
'/companies/{companyId}/connections/{connectionId}/data/commerce-info':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get company info
tags:
- Company info
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyInfo'
operationId: get-company-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:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List locations
tags:
- Locations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LocationsResponse'
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-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:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List orders
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Orders'
operationId: list-orders
description: Get a list of orders placed or held on the linked commerce platform
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
'/companies/{companyId}/connections/{connectionId}/data/commerce-payments':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List payments
tags:
- Payments
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Payments'
operationId: list-payments
description: List commerce payments for the given company & data connection.
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
'/companies/{companyId}/connections/{connectionId}/data/commerce-paymentMethods':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List payment methods
tags:
- Payments
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethods'
operationId: list-payment-methods
description: 'Retrieve a list of payment methods, such as card, cash or other online payment methods, as held in the linked commerce platform.'
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
'/companies/{companyId}/connections/{connectionId}/data/commerce-products':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List products
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Products'
operationId: list-products
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
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:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List transactions
tags:
- Transactions
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Transactions'
operationId: list-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:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
'/companies/{companyId}/connections/{connectionId}/data/commerce-productCategories':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List product categories
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ProductCategories'
operationId: list-product-categories
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
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:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: List tax components
tags:
- Tax components
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TaxComponents'
examples:
Example:
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-tax-components
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.
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=companyInfo) for this data type.
type: object
allOf:
- type: object
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:
$ref: '#/components/schemas/Address'
phoneNumbers:
type: array
description: Phone numbers associated with the company
items:
$ref: '#/components/schemas/PhoneNumber'
webLinks:
description: Weblinks associated with the company
type: array
items:
$ref: '#/components/schemas/CompanyInfo/definitions/webLink'
registrationNumber:
description: The registration number of the company
type: string
examples:
- 10480375
baseCurrency:
$ref: '#/components/schemas/Transaction/allOf/1/properties/currency'
accountBalances:
description: The available and current cash balances for the company's accounts
type: array
items:
$ref: '#/components/schemas/CompanyInfo/definitions/accountBalance'
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'
- $ref: '#/components/schemas/CreatedDate'
- $ref: '#/components/schemas/ModifiedDates'
definitions:
accountBalance:
title: Account Balance
type: object
x-internal: true
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:
- $ref: '#/components/schemas/Transaction/allOf/1/properties/currency'
webLink:
title: Weblink
description: Weblink associated with the company
x-internal: true
type: object
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'
Customer:
title: Customer
description: |-
When a customer places an order with the connected commerce store their details are added to the Customers dataset. You can use the data from the Customers endpoints to calculate key metrics, such as customer churn.
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=commerce-customers) for this data type.
type: object
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
- 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:
$ref: '#/components/schemas/PhoneNumber/properties/number'
defaultCurrency:
allOf:
- description: |
Default currency of any transactional data for the customer,
for example, orders or payments
- $ref: '#/components/schemas/Transaction/allOf/1/properties/currency'
addresses:
type: array
description: Addresses of the customer
items:
$ref: '#/components/schemas/Address'
note:
type: string
description: Any additional information about the customer
- $ref: '#/components/schemas/CreatedDate'
- $ref: '#/components/schemas/ModifiedDates'
definitions:
customerRef:
type: object
description: Reference to the customer that placed the order.
properties:
id:
description: The unique identitifer of the customer being referenced
type: string
examples:
- 13d946f0-c5d5-42bc-b092-97ece17923ab
- 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2
- 7110701885
- EILBDVJVNUAGVKRQ
name:
description: Name of the customer being referenced.
type: string
required:
- id
- name
examples:
- customers:
- id: '15'
customerName: Daffy Duck
emailAddress: d.duck@warnerbros.com
defaultCurrency: GBP
phone: (877) 492-8687
addresses:
- type: billing
line1: 301 Duck Pond
line2: 28 Green Street
city: London
region: England
country: United Kingdom
postalCode: WX1X 0BE
- type: delivery
line1: Bread Street
line2: Bird Avenue
city: Paris
region: France
country: France
postalCode: WDF 123
note: Regular customer
createdDate: '0001-01-01T00:00:00'
modifiedDate: null
sourceModifiedDate: '2020-09-15T23:52:28'
- id: '18'
customerName: Tasmanian Devil
emailAddress: t.devil@warnerbros.com
defaultCurrency: GBP
phone: +1-202-555-0181
addresses:
- type: billing
line1: 101 Fire Rooms
line2: Engine Street
city: London
region: England
country: United Kingdom
postalCode: WC1X 0BE
note: Handle with care
createdDate: '0001-01-01T00:00:00'
modifiedDate: null
sourceModifiedDate: '2020-04-16T02:41:52'
- id: a99f5e0c-a4db-452f-8d2c-8fd15482b384
customerName: Bugs Bunny
emailAddress: b.bunny@warnerbros.com
defaultCurrency: GBP
phone: ''
addresses:
- type: billing
line1: 301 Carrot Street
line2: Orange Town
city: Yorkshire
region: England
country: United Kingdom
postalCode: WF1X 0BE
- type: delivery
line1: 424 Field Street
line2: The Meadow
city: Paris
region: France
country: France
postalCode: WDF 123
note: Regular customer
createdDate: '0001-01-01T00:00:00'
modifiedDate: null
sourceModifiedDate: '2020-08-12T14:37:37'
Customers:
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Customer'
- $ref: '#/components/schemas/PagingInfo'
Dispute:
title: Dispute
description: |-
A customer may file a payment dispute with their bank or other card issuer when they're unsatisfied with their purchase or believe they have been charged incorrectly. For example:
- They didn't receive an order.
- The product they received was different to the commerce store's description.
- They've been the victim of online fraud.
You can use data from the Disputes endpoints to calculate key metrics, such as the number of chargebacks.
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=commerce-disputes) for this data type.
type: object
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
- type: object
required:
- currency
properties:
disputedTransactions:
description: Link to the source event which triggered this transaction.
$ref: '#/components/schemas/Transaction/definitions/transactionSourceRef'
totalAmount:
description: Total transaction amount that is under dispute.
type: number
examples:
- 194.12
- -283.56
- 0
currency:
description: Currency of the disputed transaction.
$ref: '#/components/schemas/Transaction/allOf/1/properties/currency'
status:
$ref: '#/components/schemas/Dispute/definitions/disputeStatus'
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
$ref: '#/components/schemas/DateTime'
- $ref: '#/components/schemas/CreatedDate'
- $ref: '#/components/schemas/ModifiedDates'
definitions:
disputeStatus:
description: Current status of the dispute
x-internal: true
type: string
enum:
- Won
- Lost
- Accepted
- Processing
- ChargeRefunded
- EvidenceRequired
- InquiryEvidenceRequired
- InquiryProcessing
- InquiryClosed
- WaitingThirdParty
- Unknown
example: EvidenceRequired
examples:
- id: 03e608e3-bd1c-454f-8c2b-fb0133e43b95
disputedTransactions:
- id: e63ad857-7e12-4e64-9185-cdfd7c45d09d
type: Order
totalAmount: -47.66
currency: GBP
status: InquiryEvidenceRequired
reason: Unhappy with product
dueDate: '2021-03-29T14:39:55'
createdDate: '2021-03-22T14:39:55'
modifiedDate: '2022-02-02T11:02:45Z'
sourceModifiedDate: '2021-03-22T14:39:55'
Disputes:
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Dispute'
- $ref: '#/components/schemas/PagingInfo'
Locations:
title: Locations
type: object
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.
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=commerce-locations) for this data type.
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
- type: object
properties:
name:
description: Name of this location
type: string
address:
description: Address associated with the location
$ref: '#/components/schemas/Address'
- $ref: '#/components/schemas/ModifiedDates'
definitions:
locationRef:
type: object
description: Reference to the geographic location where the order was placed.
properties:
id:
description: The unique identitifer of the location being referenced.
type: string
examples:
- 13d946f0-c5d5-42bc-b092-97ece17923ab
- 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2
- 7110701885
- EILBDVJVNUAGVKRQ
name:
description: Name of the location being referenced.
type: string
required:
- id
- name
examples:
- id: '15'
name: London Warehouse
address:
type: Inventory
line1: Warner House
line2: 98 Theobald's Road
city: London
region: ''
country: United Kingdom
postalCode: WC1X 8WB
modifiedDate: '2020-08-12T14:37:37'
sourceModifiedDate: '2020-08-12T14:37:37'
LocationsResponse:
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Locations'
- $ref: '#/components/schemas/PagingInfo'
Order:
title: Order
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. You can use data from the Orders endpoints to calculate key metrics, such as gross sales values and monthly recurring revenue (MRR).
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=commerce-orders) for this data type.
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:
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:
- $ref: '#/components/schemas/Transaction/allOf/1/properties/currency'
- 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.'
$ref: '#/components/schemas/DateTime'
totalAmount:
description: 'Total amount of the order, including tax, net of any discounts and refunds.'
type: number
totalRefund:
description: Total amount refunded issued by a merchant on an order (always a negative value).
type: number
totalTaxAmount:
description: Total amount of tax applied to the order.
type: number
totalDiscount:
description: Total amount of discount applied to the order.
type: number
totalGratuity:
description: Extra amount added to a bill.
type: number
orderLineItems:
type: array
items:
$ref: '#/components/schemas/Order/definitions/orderLineItem'
payments:
type: array
items:
$ref: '#/components/schemas/Payment/definitions/paymentRef'
serviceCharges:
type: array
items:
$ref: '#/components/schemas/Order/definitions/serviceCharge'
locationRef:
$ref: '#/components/schemas/Locations/definitions/locationRef'
customerRef:
$ref: '#/components/schemas/Customer/definitions/customerRef'
- $ref: '#/components/schemas/CreatedDate'
- $ref: '#/components/schemas/ModifiedDates'
definitions:
orderLineItem:
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
- type: object
properties:
quantity:
type: number
description: |
Number of units of the product sold.
For refunds, quantity is a negative value.
taxPercentage:
type: number
description: Percentage rate (from 0 to 100) of any sale tax applied to the unit amount.
examples:
- 0
- 12.5
- '45.00'
totalAmount:
type: number
description: 'Total price of the line item, including discounts, tax and minus any refunds.'
totalTaxAmount:
type: number
description: Total amount of tax applied to the line item.
unitPrice:
type: number
description: Price per unit of goods or service.
taxes:
type: array
items:
$ref: '#/components/schemas/TaxComponent/definitions/taxComponentAllocation'
description: Taxes breakdown as applied to order lines.
productRef:
$ref: '#/components/schemas/Product/definitions/productRef'
productVariantRef:
$ref: '#/components/schemas/Product/definitions/productVariantRef'
discountAllocations:
type: array
items:
$ref: '#/components/schemas/Order/definitions/orderDiscountAllocation'
serviceCharge:
type: object
x-internal: null
properties:
description:
description: Service charges for this order.
type: string
example: A service charge
totalAmount:
description: 'Total service charge, including taxes.'
type: number
examples:
- 0
- 12.5
- 45
taxPercentage:
description: Percentage rate (from 0 to 100) of any tax applied to the service charge.
type: number
examples:
- 0
- 12.5
- 45
taxAmount:
description: Amount of the service charge that is tax.
type: number
examples:
- 0
- 12.5
- 45
taxes:
description: Taxes breakdown as applied to service charges.
type: array
items:
$ref: '#/components/schemas/TaxComponent/definitions/taxComponentAllocation'
quantity:
description: The number of times the charge is charged.
type: integer
examples:
- 1
- 12
- 45
type:
$ref: '#/components/schemas/Order/definitions/serviceChargeType'
serviceChargeType:
x-internal: true
description: The type of the service charge.
type: string
enum:
- Generic
- Shipping
- Overpayment
- Unknown
example: Overpayment
orderDiscountAllocation:
type: object
x-internal: true
properties:
name:
type: string
description: Name of the discount in the commerce or point of sale platform.
example: Promotional Discount
totalAmount:
type: number
description: Total amount of discount applied.
example: 15.25
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'
Orders:
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Order'
- $ref: '#/components/schemas/PagingInfo'
Payment:
title: Payment
description: |-
Payments contain details of all payments made by customers to a company, including: amounts, currency used, payment method, payment provider, and payment status.
Refunds are recorded as separate, negative payments. Note that a refund can only occur in relation to a payment that has been completed (i.e. has a status of `Paid`). When a customer cancels an order _before_ a payment has been completed, the payment shows as `Cancelled`.
You can use data from the Payments endpoints to calculate key metrics, such as gross sales and monthly recurring revenue (MRR).
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=commerce-payments) for this data type.
type: object
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
- type: object
properties:
amount:
type: number
description: Payment Amount (including gratuity)
examples:
- 194.12
- -283.56
- 0
currency:
$ref: '#/components/schemas/Transaction/allOf/1/properties/currency'
description: Currency in which the payment was made
paymentMethodRef:
$ref: '#/components/schemas/PaymentMethod/definitions/paymentMethodRef'
status:
$ref: '#/components/schemas/Payment/definitions/paymentStatus'
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
$ref: '#/components/schemas/DateTime'
- $ref: '#/components/schemas/CreatedDate'
- $ref: '#/components/schemas/ModifiedDates'
definitions:
paymentStatus:
type: string
x-internal: true
description: Status of the payment
enum:
- Pending
- Authorized
- Paid
- Failed
- Cancelled
- Unknown
paymentType:
type: string
x-internal: true
nullable: true
description: Status of the payment
enum:
- Cash
- Card
- Invoice
- OnlineCard
- Swish
- Vipps
- Mobile
- StoreCredit
- Paypal
- Custom
- Prepaid
- Unknown
example: Cash
paymentRef:
x-internal: true
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
- type: object
properties:
amount:
type: number
nullable: true
description: Payment Amount (including gratuity).
examples:
- 194.12
- -283.56
- 0
currency:
$ref: '#/components/schemas/Transaction/allOf/1/properties/currency'
description: Currency in which the payment was made.
type:
$ref: '#/components/schemas/Payment/definitions/paymentType'
status:
$ref: '#/components/schemas/Payment/definitions/paymentStatus'
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
$ref: '#/components/schemas/DateTime'
- $ref: '#/components/schemas/CreatedDate'
- $ref: '#/components/schemas/ModifiedDates'
Payments:
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Payment'
- $ref: '#/components/schemas/PagingInfo'
PaymentMethod:
title: Payment Method
description: |-
A Payment Method represents the payment method(s) used to make payments.
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=commerce-paymentMethods) for this data type.
type: object
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
- type: object
properties:
name:
type: string
description: The name of the PaymentMethod
example: Alipay
status:
$ref: '#/components/schemas/PaymentMethod/definitions/paymentMethodStatus'
- $ref: '#/components/schemas/ModifiedDates'
definitions:
paymentMethodRef:
type: object
description: The payment method the payment is linked to in the commerce platform.
properties:
id:
description: The unique identitifer of the location being referenced.
type: string
name:
description: Name of the location being referenced.
type: string
required:
- id
- name
example:
id: EILBDVJVNUAGVKRQ
name: AliPay
paymentMethodStatus:
type: string
enum:
- Active
- Archived
- Unknown
description: Status of the Payment Method
example: Active
PaymentMethods:
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/PaymentMethod'
- $ref: '#/components/schemas/PagingInfo'
Product:
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.
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=commerce-products) for this data type.
type: object
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
- 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:
$ref: '#/components/schemas/Product/definitions/productVariant'
definitions:
productRef:
type: object
description: Reference that links the line item to the correct product details.
properties:
id:
description: The unique identitifer of the product being referenced.
type: string
examples:
- 13d946f0-c5d5-42bc-b092-97ece17923ab
- 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2
- 7110701885
- EILBDVJVNUAGVKRQ
name:
description: Name of the product being referenced.
type: string
required:
- id
- name
productVariant:
title: Product Variant
x-internal: true
description: |
Represents a variation of a product available for sale, for example an item of clothing that may be available for sale in multiple sizes and colors.
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
description: 'Identifier of the product variant, unique to the company.'
- properties:
name:
type: string
examples:
- Red Coat
- Black Coat
- Large Brown Hat
description: Name of the product recorded in the commerce or point of sale platform.
quantity:
type: number
examples:
- 0
- 10
- 100.54
isTaxEnabled:
type: boolean
description: Whether sales taxes are enabled for this product variant.
sku:
type: string
examples:
- Coat-Red-Lrg
- Coat-Black-Md
- LargeBrownHat
- A725BA2
description: 'SKU (stock keeping unit) of the variant, as defined by the merchant.'
barcode:
type: string
examples:
- '564158468416486458646886484'
- CSE370
description: 'Unique product number of the variant. This might be a barcode, UPC, ISBN, etc.'
unitOfMeasure:
type: string
examples:
- kg
- m
- meters
description: 'Unit of measure for the variant, such as `kg` or `meters`.'
vatPercentage:
type: number
examples:
- 12.5
- 0
- 20
description: VAT rate for the product variant if sales taxes are enabled.
prices:
type: array
description: Prices for the product variants in different currencies.
items:
$ref: '#/components/schemas/Product/definitions/productPrice'
inventory:
type: array
description: Information about the total inventory as well as the locations inventory is in.
items:
$ref: '#/components/schemas/Product/definitions/productInventory'
shippingRequired:
type: boolean
description: Indicates whether or not the product requires physical delivery.
status:
$ref: '#/components/schemas/Product/definitions/productVariantStatus'
- $ref: '#/components/schemas/CreatedDate'
- $ref: '#/components/schemas/ModifiedDates'
productVariantRef:
title: Product Variant Ref
type: object
description: Reference that links the line item to the specific version of product that has been ordered.
properties:
id:
description: The unique identitifer of the product variant being referenced.
type: string
examples:
- 13d946f0-c5d5-42bc-b092-97ece17923ab
- 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2
- 7110701885
- EILBDVJVNUAGVKRQ
name:
description: Name of the product variant being referenced.
type: string
required:
- id
- name
productPrice:
title: Product Price Variant
x-internal: true
type: object
properties:
currency:
$ref: '#/components/schemas/Transaction/allOf/1/properties/currency'
nullable: true
unitPrice:
type: number
productInventory:
title: Product Inventory
x-internal: true
type: object
properties:
totalQuantity:
type: number
nullable: true
locations:
type: array
items:
$ref: '#/components/schemas/Product/definitions/productInventoryLocation'
productInventoryLocation:
title: Product Inventory Location
x-internal: true
type: object
properties:
quantity:
type: number
locationRef:
$ref: '#/components/schemas/Locations/definitions/locationRef'
productVariantStatus:
x-internal: true
type: string
enum:
- Unknown
- Published
- Unpublished
Products:
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Product'
- $ref: '#/components/schemas/PagingInfo'
ProductCategory:
title: Product Category
description: |-
Product categories are used to classify a group of products together, either by type (e.g. "Furniture"), or sometimes by tax profile.
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=commerce-productCategories) for this data type.
type: object
allOf:
- type: object
properties:
id:
type: string
example: '"102"'
description: The unique identifier of the product category
name:
type: string
example: Entertainment
description: The name of the product category
ancestorRefs:
type: array
description: A collection of parent product categories implicitly ordered with the immediate parent last in the list.
items:
$ref: '#/components/schemas/RecordRef'
hasChildren:
type: boolean
description: A boolean indicating whether there are other product categories beneath this one in the hierarchy.
- $ref: '#/components/schemas/ModifiedDates'
examples:
- productCategories:
- id: '100'
name: Entertainment
ancestorRefs: []
hasChildren: true
modifiedDate: '2022-01-01T12:00:00Z'
sourceModifiedDate: '2021-10-01T12:53:21Z'
- id: '101'
name: Cinema
ancestorRefs:
- id: '100'
name: Entertainment
hasChildren: true
modifiedDate: '2022-01-01T12:00:00Z'
sourceModifiedDate: '2021-10-01T12:55:02Z'
- id: '102'
name: Movie
ancestorRefs:
- id: '100'
name: Entertainment
- id: '101'
name: Cinema
hasChildren: false
modifiedDate: '2022-01-01T12:00:00Z'
sourceModifiedDate: '2021-12-25T12:00:00Z'
ProductCategories:
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/ProductCategory'
- $ref: '#/components/schemas/PagingInfo'
TaxComponent:
title: Tax Component
description: |-
The Tax Components endpoints return tax rates data from the commerce platform, including tax rate names and values. This is to support the mapping of tax rates from the commerce platform to those in the accounting platform.
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=commerce-disputes) for this data type.
type: object
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
- 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
- $ref: '#/components/schemas/ModifiedDates'
required:
- name
definitions:
taxComponentAllocation:
title: Tax Component Allocation
type: object
properties:
taxComponentRef:
$ref: '#/components/schemas/TaxComponent/definitions/taxComponentRef'
rate:
description: Tax amount on order line sale as available from source commerce platform.
type: number
nullable: true
taxComponentRef:
type: object
description: Taxes rates reference object depending on the rates being available on source commerce package.
properties:
id:
description: The unique identitifer of the tax component being referenced.
type: string
examples:
- 13d946f0-c5d5-42bc-b092-97ece17923ab
- 9wg4lep4ush5cxs79pl8sozmsndbaukll3ind4g7buqbm1h2
- 7110701885
- EILBDVJVNUAGVKRQ
name:
description: Name of the tax component being referenced.
type: string
required:
- id
- name
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'
TaxComponents:
x-iternal: true
type: object
properties:
taxComponents:
type: array
items:
$ref: '#/components/schemas/TaxComponent'
Transaction:
title: Transaction
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.
You can use data from the Transactions endpoints to calculate key metrics, such as:
- Transaction volumes
- Average transaction volume
- Average transaction value
- Returns
- Payouts
Explore our [data coverage](https://knowledge.codat.io/supported-features/commerce?view=tab-by-data-type&dataType=commerce-transactions) for this data type.
type: object
allOf:
- $ref: '#/components/schemas/Order/allOf/0'
- 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:
$ref: '#/components/schemas/Transaction/definitions/transactionType'
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:
- $ref: '#/components/schemas/Transaction/definitions/transactionSourceRef'
- allOf:
- type: object
x-stoplight:
id: c590b4405180f
allOf:
- $ref: '#/components/schemas/CreatedDate'
- type: object
x-stoplight:
id: gdyjg7bg783br
properties:
sourceCreatedDate:
$ref: '#/components/schemas/DateTime'
description: The date on which this record was created in the originating system
- $ref: '#/components/schemas/ModifiedDates'
x-stoplight:
id: 9e815c1766554
definitions:
transactionSourceRef:
title: Transaction Source Reference
x-internal: true
allOf:
- $ref: '#/components/schemas/RecordRef'
- type: object
properties:
type:
$ref: '#/components/schemas/Transaction/definitions/transactionSourceType'
transactionSourceType:
x-internal: true
type: string
enum:
- Fee
- Order
- Payment
- ServiceCharge
- Unknown
transactionType:
x-iternal: true
description: |-
The type of the platform transaction:
- `Unknown`
- `FailedPayout` — Failed transfer of funds from the seller's merchant account to their bank account.
- `Payment` — Credit and debit card payments.
- `PaymentFee` — Payment provider's fee on each card payment.
- `PaymentFeeRefund` — Payment provider's fee that has been refunded to the seller.
- `Payout` — Transfer of funds from the seller's merchant account to their bank account.
- `Refund` — Refunds to a customer's credit or debit card.
- `Transfer` — Secure transfer of funds to the seller's bank account.
type: string
enum:
- Payment
- Refund
- Payout
- FailedPayout
- Transfer
- PaymentFee
- PaymentFeeRefund
- Unknown
examples: []
Transactions:
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Transaction'
- $ref: '#/components/schemas/PagingInfo'
Address:
title: Address
x-internal: true
type: object
properties:
type:
$ref: '#/components/schemas/Address/definitions/addressType'
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
definitions:
addressType:
description: The type of the address
x-internal: true
type: string
enum:
- Billing
- Delivery
- Order
- Inventory
- Unknown
PagingInfo:
type: object
x-internal: true
properties:
pageNumber:
type: integer
pageSize:
type: integer
totalResults:
type: integer
_links:
$ref: '#/components/schemas/Links'
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'
PhoneNumber:
type: object
properties:
number:
title: Phone Number
x-internal: true
type: string
description: A phone number
examples:
- +44 25691 154789
- (877) 492-8687
- 01224 658 999
type:
$ref: '#/components/schemas/PhoneNumber/definitions/phoneNumberType'
required:
- number
- type
definitions:
phoneNumberType:
x-internal: true
description: The type of phone number
type: string
enum:
- Primary
- Landline
- Mobile
- Fax
- Unknown
RecordRef:
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: ''
Links:
type: object
x-internal: true
required:
- self
- current
properties:
self:
$ref: '#/components/schemas/HRef'
current:
$ref: '#/components/schemas/HRef'
next:
$ref: '#/components/schemas/HRef'
previous:
$ref: '#/components/schemas/HRef'
examples:
- self:
href: '/companies/{id}/data/{dataType}'
current:
href: '/companies/{id}/data/{dataType}?page=1&pageSize=10'
HRef:
title: Hypertext reference
type: object
x-internal: true
properties:
href:
type: string
format: uri-reference
DateTime:
title: Date Time
type: string
example: '2022-10-23T00:00:00Z'
description: |-
In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example:
```
2020-10-08T22:40:50Z
2021-01-01T00:00:00
```
When syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:
- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`
- Unqualified local time: `2021-11-15T01:00:00`
- UTC time offsets: `2021-11-15T01:00:00-05:00`
> Time zones
>
> Not all dates from Codat will contain information about time zones.
> Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced.
CreatedDate:
type: object
x-internal: true
properties:
createdDate:
$ref: '#/components/schemas/DateTime'
description: The date the entity was created.
ModifiedDates:
x-internal: true
allOf:
- title: ModifiedDate
x-internal: true
type: object
properties:
modifiedDate:
$ref: '#/components/schemas/DateTime'
description: The date on which this record was last modified in Codat.
- title: Source Modified Date
x-internal: true
type: object
properties:
sourceModifiedDate:
$ref: '#/components/schemas/DateTime'
description: The date on which this record was last modified in the originating system
parameters:
companyId:
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.
connectionId:
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.
page:
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
pageSize:
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
query:
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
orderBy:
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
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