Commerce: Order

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/CommerceOrder",
  "title": "Commerce: 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).\n",
  "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.\n\nDepending on the platform the value of this property will either be an <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes\" target=\"_blank\">ISO 3166</a> code (2-alpha or 3-alpha) or free-form text returned as a string name in our model. \n\nFor 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/lending-api#/operations/get-companies-companyId-connections-connectionId-push) endpoint.",
          "type": "string",
          "format": "ISO3166 Alpha-3",
          "examples": [
            "GBR",
            "USA",
            "ABW"
          ]
        },
        "currency": {
          "allOf": [
            {
              "$ref": "#/components/schemas/SourceAccount/properties/currency"
            },
            {
              "description": "Currency in which the order was placed."
            }
          ]
        },
        "closedDate": {
          "$ref": "#/components/schemas/DateTime",
          "description": "Date on which order was closed after the product was shipped, paid for, and any refund period had elapsed."
        },
        "totalAmount": {
          "description": "Total amount of the order, including discounts, refunds, and tax, but excluding gratuities.",
          "type": "number",
          "format": "decimal"
        },
        "totalRefund": {
          "description": "Total amount of any refunds issued on the order, including discounts and tax, but excluding gratuities. This is always negative.",
          "type": "number",
          "format": "decimal"
        },
        "totalTaxAmount": {
          "description": "Total amount of tax applied to the order.",
          "type": "number",
          "format": "decimal"
        },
        "totalDiscount": {
          "description": "Total amount of any discounts applied to the order, excluding tax. This is typically positive (for discounts which decrease the amount of the order), but can also be negative (for discounts which increase the amount of the order).",
          "type": "number",
          "format": "decimal"
        },
        "totalGratuity": {
          "description": "Extra amount added to the order.",
          "type": "number",
          "format": "decimal"
        },
        "orderLineItems": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/CommerceOrder/definitions/orderLineItem"
          }
        },
        "payments": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/CommercePayment/definitions/paymentRef"
          }
        },
        "serviceCharges": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/CommerceOrder/definitions/serviceCharge"
          }
        },
        "locationRef": {
          "$ref": "#/components/schemas/CommerceLocation/definitions/locationRef"
        },
        "customerRef": {
          "$ref": "#/components/schemas/CommerceCustomer/definitions/commerceCustomerRef"
        },
        "supplementalData": {
          "$ref": "#/components/schemas/SupplementalData"
        }
      }
    },
    {
      "title": "Created date",
      "type": "object",
      "x-internal": true,
      "properties": {
        "createdDate": {
          "$ref": "#/components/schemas/DateTime",
          "description": "The date the entity was created."
        }
      }
    },
    {
      "title": "Modified dates",
      "x-internal": true,
      "allOf": [
        {
          "title": "ModifiedDate",
          "x-internal": true,
          "type": "object",
          "properties": {
            "modifiedDate": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/DateTime"
                },
                {
                  "description": "The date when the record was last fetched from the accounting software, commerce software, or open banking provider and updated in Codat\u2019s data cache.\n\nUse it to identify and retrieve records that have changed since your last fetch. For example, filtering `modifiedDate` to today will provide new records updated in Codat today.\n\nThis date is populated for all data types except for attachments, balance sheets, company information, and profit & loss reports ([read more](https://docs.codat.io/using-the-api/modified-dates#modified-date)).\n\nIn Codat's data model, dates and times are represented using the <a class=\"external\" href=\"https://en.wikipedia.org/wiki/ISO_8601\" target=\"_blank\">ISO 8601 standard</a>."
                }
              ]
            }
          }
        },
        {
          "title": "Source Modified Date",
          "x-internal": true,
          "type": "object",
          "nullable": true,
          "properties": {
            "sourceModifiedDate": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/DateTime"
                },
                {
                  "description": "The date when a record was last modified in the accounting software, usually by the business or a business process. For example, when payments are made against an invoice. \n\nIt is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when:\n  - Pulling attachments\n  - The accounting software does not provide modification dates for a data type\n  - A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred\n  - A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records\n\nIn Codat's data model, dates and times are represented using the <a class=\"external\" href=\"https://en.wikipedia.org/wiki/ISO_8601\" target=\"_blank\">ISO 8601 standard</a>."
                }
              ]
            }
          }
        }
      ]
    }
  ],
  "definitions": {
    "orderLineItem": {
      "allOf": [
        {
          "$ref": "#/components/schemas/CommerceOrder/allOf/0"
        },
        {
          "type": "object",
          "properties": {
            "quantity": {
              "type": "number",
              "format": "decimal",
              "description": "Number of units of the product sold.\nFor refunds, quantity is negative.\n"
            },
            "taxPercentage": {
              "type": "number",
              "format": "decimal",
              "description": "Percentage rate (from 0 to 100) of any sales tax applied to the unit price.",
              "examples": [
                0,
                12.5,
                "45.00"
              ]
            },
            "totalAmount": {
              "type": "number",
              "format": "decimal",
              "description": "Total amount of the line item, including discounts and tax."
            },
            "totalTaxAmount": {
              "type": "number",
              "format": "decimal",
              "description": "Total amount of tax applied to the line item, factoring in any discounts."
            },
            "unitPrice": {
              "type": "number",
              "format": "decimal",
              "description": "Price per unit of goods or services, excluding discounts and tax."
            },
            "taxes": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/CommerceTaxComponent/definitions/taxComponentAllocation"
              },
              "description": "Taxes breakdown as applied to order lines."
            },
            "productRef": {
              "$ref": "#/components/schemas/CommerceProduct/definitions/productRef"
            },
            "productVariantRef": {
              "$ref": "#/components/schemas/CommerceProduct/definitions/productVariantRef"
            },
            "discountAllocations": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/CommerceOrder/definitions/orderDiscountAllocation"
              }
            }
          }
        }
      ]
    },
    "serviceCharge": {
      "type": "object",
      "properties": {
        "description": {
          "description": "Service charges for this order.",
          "type": "string",
          "example": "A service charge"
        },
        "totalAmount": {
          "description": "Total amount of the service charge, including tax.",
          "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": {
            "$ref": "#/components/schemas/CommerceTaxComponent/definitions/taxComponentAllocation"
          }
        },
        "quantity": {
          "description": "The number of times the charge is charged.",
          "type": "integer",
          "examples": [
            1,
            12,
            45
          ]
        },
        "type": {
          "$ref": "#/components/schemas/CommerceOrder/definitions/serviceChargeType"
        }
      }
    },
    "serviceChargeType": {
      "description": "The type of the service charge.",
      "type": "string",
      "enum": [
        "Generic",
        "Shipping",
        "Overpayment",
        "Unknown"
      ],
      "example": "Overpayment"
    },
    "orderDiscountAllocation": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the discount in the commerce or point of sale platform.",
          "example": "Promotional Discount"
        },
        "totalAmount": {
          "type": "number",
          "format": "decimal",
          "description": "Total amount of discount applied, excluding tax. This is typically positive (for discounts which decrease the amount of the order line), but can also be negative (for discounts which increase the amount of the order line).",
          "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"
    }
  ],
  "type": "object"
}