Orders

Explore the Commerce Orders endpoints in Swagger.

You can use data from the Orders endpoints to calculate key metrics, such as gross sales values and monthly recurring revenue (MRR).

View the coverage for orders in the Data Coverage Explorer.

Overview

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.

Data model

Field	Type	Description
id	string	Identifier of the order, unique to the company.
orderNumber	string	Friendly reference for the order in the commerce or point of sale platform.
country	string	ISO code for the country where the order was placed.
currency	string See currency	Currency in which the order was placed.
createdDate	string See date	Date on which the order was first recorded in the commerce or point of sale platform.
closedDate	string (optional)	Date on which order was closed after the product was shipped, paid for, and any refund period had elapsed.
totalAmount	decimal	Total amount of the order, including tax, net of any discounts and refunds.
totalRefund	decimal	Total amount refunded issued by a merchant on an order (always a negative value).
totalTaxAmount	decimal	Total amount of tax applied to the order.
totalDiscount	decimal	Total amount of discount applied to the order.
totalGratuity	decimal	Extra amount added to a bill.
orderLineItems	array See order line items	Line items relating to the order.
payments	array See payments	Payments for this order.
serviceCharges	array See serviceCharges	Service charges for this order.
locationRef	reference type	Reference to the geographic location where the order was placed.
customerRef	reference type	Reference to the customer that placed the order.
modifiedDate	string See date	Date the order was last updated in the Codat system.
sourceModifiedDate	string See date	Date the order was last changed in the commerce or point of sale platform.

Order line items

Field	Type	Description
id	string	Identifier of the line item, unique to the order.
quantity	decimal	Number of units of the product sold. For refunds, quantity is a negative value.
taxPercentage	decimal	Percentage rate (from 0 to 100) of any sale tax applied to the unit amount.
totalAmount	decimal	Total price of the line item, including discounts, tax and minus any refunds.
totalTaxAmount	decimal	Total amount of tax applied to the line item.
unitPrice	decimal	Price per unit of goods or service.
productRef	reference type	Reference that links the line item to the correct product details.
productVariantRef	reference type	Reference that links the line item to the specific version of product that has been ordered.
discountAllocations	array See discountAllocations.	Discounts applied to this line item.

Discount allocations

Details or any discounts applied to an order line item.

Field	Type	Description
name	string	Name of the discount in the commerce or point of sale platform.
totalAmount	decimal	Total amount of discount applied.

Payments

Details of a customer's payment for their order.
See payments.

Service charges

Details of any service charges applied to the order.

Field	Type	Description
description	string	Description of the service charge.
totalAmount	decimal	Total service charge, including taxes.
taxPercentage	decimal	Percentage rate (from 0 to 100) of any tax applied to the service charge.
taxAmount	decimal	Amount of the service charge that is tax.
quantity	integer	Number of times the service charge is applied to a purchase.
type	string	Type of service charge applied: `Unknown` `Generic` `Shipping` `Overpayment`

Example data

{
      "id": "01e63721-1205-478e-8503-9d8bf8a93f44",
      "orderNumber": "99123956",
      "country": "CAN",
      "currency": "CAD",
      "createdDate": "2021-03-28T03:00:14",
      "totalAmount": 12.00,
      "totalRefund": 0,
      "totalTaxAmount": 2.00,
      "totalDiscount": 0,
      "totalGratuity": 1.00,
      "orderLineItems": [
        {
          "id": "116113a6-54d3-4624-ba73-26a77a5ffd51",
          "quantity": 1,
          "taxPercentage": 20,
          "totalAmount": 12.00,
          "totalTaxAmount": 2.00,
          "unitPrice": 10.00,
          "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.00,
          "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.20,
          "taxPercentage": 20,
          "taxAmount": 0.20,
          "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"
    }