--- updatedAt: 2026-06-08T07:54:20.000Z agentTools: projectIndex: https://triplewhale.readme.io/llms.txt --- # Create Order Record Ingest order data into Triple Whale for Custom Sales Platforms. This endpoint allows users to upload detailed order information, including customer details, product information, transaction totals, discounts, refunds, and shipping details. > 📘 Sending Order Data > > **When to Use This Endpoint** > > This endpoint is intended for ingesting custom order data only (Custom Sales Platform). If your store already uses a native Triple Whale integration — such as Shopify, BigCommerce, or WooCommerce — use the [Enrich Orders Data](https://triplewhale.readme.io/reference/enrich-orders-data#/) endpoint instead to enrich your natively-integrated order records. > > **Match Order and Product Platform Values** > > To apply product-based COGS and handling fees to orders, the `platform` and `platform_account_id` values sent in order records must exactly match the values sent in the matching [product records](https://triplewhale.readme.io/reference/create-product-record#/). > > **How to Update a Custom Order Record** > > To update a custom order record, resend the order with all of the following fields exactly matching the original: > > `shop`, `order_id`, `refund_id`, `created_at`, `refunded_at,` `platform`, `platform_account_id` > > All other fields will be **overwritten** with the newly sent values. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Triple Whale API", "version": "1.0", "description": "Triple Whale API documentation, providing endpoints for managing user authentication, API key validation, and uploading data such as ads and metrics.\n" }, "servers": [ { "url": "https://api.triplewhale.com/api/v2/" } ], "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } } }, "security": [ { "apiKeyAuth": [] } ], "paths": { "/data-in/orders": { "post": { "summary": "Create Order Record", "description": "Ingest order data into Triple Whale for Custom Sales Platforms. This endpoint allows users to upload detailed order information, including customer details, product information, transaction totals, discounts, refunds, and shipping details.\n", "operationId": "create-order-record", "tags": [ "Data In" ], "security": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "shop", "order_id", "created_at", "currency", "customer", "order_revenue" ], "properties": { "shop": { "type": "string", "description": "The unique identifier for the shop (e.g., `example.myshopify.com`). This is the `shop-id` value in your Triple Whale app URL (for example `?shop-id=example.myshopify.com`). The API key owner must also have access to the shop, otherwise the request will return 403. Maps to `shop_id` in the Orders table.\n", "example": "example.myshopify.com" }, "order_id": { "type": "string", "description": "The unique identifier for the order.", "example": "order_12345" }, "platform": { "type": "string", "description": "The sales platform where the order originated. Note that for custom sales platforms, the platform will appear as `custom-msp` in SQL queries the Triple Whale app, regardless of the value sent. To apply product-based COGS and handling fees to orders, this value must exactly match the `platform` value sent in the matching product records.\n", "default": "custom-msp", "example": "magento" }, "platform_account_id": { "type": "string", "description": "The account ID associated with the platform. To apply product-based COGS and handling fees to orders, this value must exactly match the `platform_account_id` value sent in the matching product records.\n", "default": "custom-msp", "example": "shop_account_123" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the order record was created. Must be provided in ISO 8601 format, with explicit timezone information (`Z` or `+/-HH:mm` offset). Offsets are supported (e.g., `2022-06-15T21:26:30+02:00`). Maps to `created_at` in the Orders table and is used to derive `event_date`, which reflects the shop time zone.\n", "example": "2022-06-15T19:26:30.000Z" }, "currency": { "type": "string", "description": "The currency in which the transaction was processed (e.g. `USD`, `EUR`).", "example": "USD" }, "customer": { "type": "object", "description": "Details of the customer who placed the order. The `id` field is required. Additionally, at least one of `email` or `phone` must be provided.\n", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The unique identifier for the customer. Maps to `customer_id` in the Orders table.", "example": "customer_123" }, "email": { "type": "string", "description": "The customer’s email address. Maps to `customer_email` in the Orders table.", "example": "customer@example.com" }, "phone": { "type": "string", "description": "The customer’s phone number.", "example": "+1234567890" }, "first_name": { "type": "string", "description": "The customer’s first name. Maps to `customer_first_name` in the Orders table.", "example": "John" }, "last_name": { "type": "string", "description": "The customer’s last name. Maps to `customer_last_name` in the Orders table.", "example": "Doe" } } }, "custom_expenses": { "type": "number", "description": "Custom expenses associated with the order, must be non-negative.", "example": 25 }, "is_new_customer": { "type": "boolean", "nullable": true, "description": "Indicates whether the order is from a new customer. If omitted or `null`, Triple Whale classifies the order automatically based on order history (a customer's first order is classified as new). Set to `true` to mark the order as a new customer order, or `false` to mark it as a returning customer order.", "example": true }, "discount_codes": { "type": "array", "description": "Discount codes applied to the order.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The discount code used in the order. Maps to `discount_code` in the Orders table.", "example": "BLACKFRIDAY" }, "amount": { "type": "number", "description": "The discount amount applied for the discount code. Must be non-negative. Note that this field does not map to `discount_amount` in the Orders table; to send total discount amount for the order, use `total_discounts`.", "example": 15.5 }, "type": { "type": "string", "description": "The type of discount applied. Use `percentage` when the discount amount represents a percentage of the order total, and `fixed_amount` when it represents a fixed monetary value in the order’s currency. Maps to `discount_type` in the Orders table.\n", "enum": [ "percentage", "fixed_amount" ], "example": "percentage" } } } }, "line_items": { "type": "array", "description": "Details of the products in the order.", "items": { "type": "object", "required": [ "id", "quantity", "price", "variant_id", "product_id" ], "properties": { "id": { "type": "string", "description": "The unique identifier for the line item.", "example": "line_item_1" }, "name": { "type": "string", "description": "The name for the line item.", "example": "Line Item 1" }, "price": { "type": "number", "description": "The price of the product. Maps to `products_info.product_name_price` in the Orders table.", "example": 20 }, "quantity": { "type": "integer", "description": "The quantity of the product in the order. Maps to `products_info.product_name_quantity_sold` in the Orders table.", "example": 2 }, "product_id": { "type": "string", "description": "The unique identifier for the product. Maps to `products_info.product_id` in the Orders table. Required for [Product Analytics](https://app.triplewhale.com/dashboards/product-analytics); must match a `product_id` sent via the `/products` endpoint.", "example": "product_123" }, "product_name": { "type": "string", "description": "The name of the product associated with this line item. Maps to `products_info.product_name` in the Orders table.", "example": "T-shirt" }, "variant_id": { "type": "string", "description": "The unique identifier for the product variant. Maps to `products_info.variant_id` in the Orders table.", "example": "variant_456" }, "variant_name": { "type": "string", "description": "The name of the product variant. Maps to `products_info.variant_name` in the Orders table.", "example": "Red T-shirt (Large)" }, "sku": { "type": "string", "description": "The stock keeping unit of the product. Maps to `products_info.product_sku` in the Orders table.", "example": "sku_123" } } } }, "name": { "type": "string", "description": "The name of the order, as assigned by the seller on the main sales platform. Maps to `order_name` in the Orders table. Defaults to `order_id` if not provided.\n", "example": "Order #12345" }, "payment_gateway_names": { "type": "array", "description": "The payment gateway used for the transaction (e.g., `shopify_payments`, `paypal`, `gift_card`). Required in order to update payment gateway settings, and to calculate `payment_gateway_costs` in the Orders table. Edit Payment Gateway Costs in [Cost Settings](https://app.triplewhale.com/cost-settings) > Gateway Costs.\n", "items": { "type": "string" }, "example": [ "paypal" ] }, "refunds": { "type": "array", "description": "Details of refunds applied to the order.", "items": { "type": "object", "required": [ "refund_id", "refunded_at", "total_refund" ], "properties": { "refund_id": { "type": "string", "description": "The unique identifier for the refund.", "example": "refund_1" }, "refunded_at": { "type": "string", "format": "date-time", "description": "The time at which the refund was processed. Must be provided in ISO 8601 format, with explicit timezone information (`Z` or `+/-HH:mm` offset). Offsets are supported (e.g., `2024-11-29T12:00:00+02:00`).\n", "example": "2024-11-29T11:00:00Z" }, "line_items": { "type": "array", "description": "Details of refunded line items.", "items": { "type": "object", "required": [ "id", "quantity", "price", "variant_id" ], "properties": { "id": { "type": "string", "description": "The unique identifier for the refunded line item.", "example": "line_item_1" }, "line_item_id": { "type": "string", "description": "The unique identifier of the line item associated with this refund line item.", "example": "line_item_1" }, "quantity": { "type": "integer", "description": "The quantity of the refunded line item.", "example": 1 }, "product_id": { "type": "string", "description": "The unique identifier for the refunded product.", "example": "product_123" }, "variant_id": { "type": "string", "description": "The unique identifier for the refunded variant.", "example": "variant_456" }, "price": { "type": "number", "description": "The price of the refunded line item.", "example": 20 }, "currency": { "type": "string", "description": "The currency of the refunded line item.", "example": "USD" }, "total_discount": { "type": "number", "description": "The total discount applied to the refunded line item.", "example": 0 } } } }, "total_refund": { "type": "number", "description": "The total amount refunded.", "example": 40 }, "total_tax_refund": { "type": "number", "description": "The total tax refunded.", "example": 3 }, "total_shipping_refund": { "type": "number", "description": "The total shipping refunded.", "example": 5 }, "tags": { "type": "array", "description": "Tags associated with the refund.", "items": { "type": "string", "example": "damaged_item" } }, "void": { "type": "boolean", "description": "Set to `true` to void (soft delete) this refund. Voided refund records are excluded from all queries. To void a refund, resend the entire Order record with all fields identical except for `\"void\": true` for this refund. [Learn more](https://triplewhale.readme.io/reference/managing-data-in-connections#voiding-records-soft-delete)\n", "default": false, "example": false } } } }, "shipping_address": { "type": "object", "description": "Shipping address details.", "properties": { "address_1": { "type": "string", "description": "The first line of the address.", "example": "123 Main Street" }, "address_2": { "type": "string", "description": "The second line of the address.", "example": "Apt 4B" }, "zip": { "type": "string", "description": "The ZIP or postal code of the address.", "example": "10001" }, "city": { "type": "string", "description": "The city of the address. Maps to `customer_from_city` in the Orders table.", "example": "New York" }, "country": { "type": "string", "description": "The country of the address.", "example": "USA" }, "country_code": { "type": "string", "description": "The country code of the address. Maps to `customer_from_country_code` in the Orders table.", "example": "US" }, "province_code": { "type": "string", "description": "The province or state code of the address. Maps to `customer_from_state_code` in the Orders table.", "example": "NY" } } }, "shipping_lines": { "type": "array", "description": "Details of the shipping lines for the order.", "items": { "type": "object", "properties": { "shipping_discounted_price": { "type": "number", "description": "The discounted price for shipping.", "example": 5 }, "shipping_price": { "type": "number", "description": "The original price for shipping.", "example": 10 }, "source": { "type": "string", "description": "The source or method of shipping.", "example": "standard_shipping" }, "title": { "type": "string", "description": "The title or description of the shipping method.", "example": "Standard Shipping" } } } }, "shipping_price": { "type": "number", "description": "The total shipping price of the order (paid by the buyer), including shipping taxes and shipping discounts.", "example": 15 }, "shipping_costs": { "type": "number", "description": "Shipping costs paid by the seller. Must be non-negative. To apply this value to your data, ensure **Default Shipping Costs** is selected in [Cost Settings](https://app.triplewhale.com/cost-settings) > Shipping.\n", "example": 15 }, "source_name": { "type": "string", "description": "The origin of the order as designated by the seller on the main sales platform (e.g. `web`, `pos`, `tiktok`).", "example": "web" }, "subscription_id": { "type": "string", "description": "The unique identifier for the subscription associated with the order.", "example": "sub_12345" }, "tags": { "type": "array", "description": "Tags associated with the order. Include a distinct tag to classify or identify specific order types or processing rules. For example, use `holiday_sale` to mark seasonal campaign purchases, or `staff_order` for internal orders.\n", "items": { "type": "string" }, "example": [ "holiday_sale", "staff_order" ] }, "taxes_included": { "type": "boolean", "description": "Indicates if taxes are included in the total price of the order.", "default": false, "example": false }, "order_revenue": { "type": "number", "description": "The total revenue after adjustments such as discounts, shipping, fees, and taxes. Must be non-negative.", "example": 150.75 }, "total_discounts": { "type": "number", "description": "The total discount amount applied to the order, including shipping discounts. Must be non-negative. Maps to `discount_amount` in the Orders table.", "example": 15.5 }, "taxes": { "type": "number", "description": "The total tax applied to the order. Must be non-negative.", "example": 8.25 }, "status": { "type": "string", "description": "The current status of the order (e.g., \"completed\", \"pending\"). Maps to `fulfillment_status` in the Orders table.", "example": "completed" }, "updated_at": { "type": "string", "format": "date-time", "description": "The time at which the order record was last updated. Must be provided in ISO 8601 format, with explicit timezone information (`Z` or `+/-HH:mm` offset). Offsets are supported (e.g., `2024-11-29T12:00:00+02:00`). Defaults to the current time.\n", "example": "2024-11-29T10:00:00Z" }, "void": { "type": "boolean", "description": "Set to `true` to void (soft delete) this order record, as well as all associated refund records (even if the refunds are not individually voided). Voided orders (and associated refunds) are excluded from all queries. To void an order record, resend it with all fields identical except for `\"void\": true`. [Learn more](https://triplewhale.readme.io/reference/managing-data-in-connections#voiding-records-soft-delete)\n", "default": false, "example": false } } } } } }, "responses": { "200": { "description": "Order record successfully received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Order received" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid order data." } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "The number of seconds until the user can make another request.", "schema": { "type": "string" }, "example": "60" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Rate limit exceeded. Try again later." } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error processing order" } } } } } } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```