---
title: "Bulk Create Order Records"
method: POST
path: "/data-in/bulk-orders"
tags: ["Data In"]
---

# Bulk Create Order Records

`POST /data-in/bulk-orders`

Ingest multiple order records into Triple Whale for Custom Sales Platforms.   This endpoint allows users to upload batches of order information, including customer details, product information, transaction totals, discounts, refunds, and shipping details.

## Request body

- object
  - `shop` string, required — The exact Shop URL (e.g., 'example.myshopify.com'). Must match the Shop URL value shown in [Settings → Store](https://app.triplewhale.com/store-settings/general). 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. This value is applied to every order in the `orders` array and overwrites any per-order `shop` value.
  - `orders` object[], required — An array of Order objects to ingest. Must contain between 1 and 1000 orders. Each order object uses the same schema as the `/data-in/orders` endpoint, except `shop` is not required (and is ignored/overwritten if provided).
    - `shop` string — Optional. If provided, it will be overwritten by the top-level `shop` value in this request.
    - `order_id` string, required — The unique identifier for the order.
    - `platform` string — 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.
    - `platform_account_id` string — 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.
    - `created_at` string, date-time, required — 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.
    - `currency` string, required — The currency in which the transaction was processed (e.g. `USD`, `EUR`).
    - `customer` object, required — Details of the customer who placed the order. The `id` field is required. Additionally, at least one of `email` or `phone` must be provided.
      - `id` string, required — The unique identifier for the customer. Maps to `customer_id` in the Orders table.
      - `email` string — The customer’s email address. Maps to `customer_email` in the Orders table.
      - `phone` string — The customer’s phone number.
      - `first_name` string — The customer’s first name. Maps to `customer_first_name` in the Orders table.
      - `last_name` string — The customer’s last name. Maps to `customer_last_name` in the Orders table.
    - `custom_expenses` number — Custom expenses associated with the order, must be non-negative.
    - `is_new_customer` boolean, nullable — 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.
    - `discount_codes` object[] — Discount codes applied to the order.
      - `code` string — The discount code used in the order. Maps to `discount_code` in the Orders table.
      - `amount` number — 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`.
      - `type` 'percentage' | 'fixed_amount' — 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.
    - `line_items` object[] — Details of the products in the order.
      - `id` string, required — The unique identifier for the line item.
      - `name` string — The name for the line item.
      - `price` number, required — The price of the product. Maps to `products_info.product_name_price` in the Orders table.
      - `quantity` integer, required — The quantity of the product in the order. Maps to `products_info.product_name_quantity_sold` in the Orders table.
      - `product_id` string, required — 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.
      - `product_name` string — The name of the product associated with this line item. Maps to `products_info.product_name` in the Orders table.
      - `variant_id` string, required — The unique identifier for the product variant. Maps to `products_info.variant_id` in the Orders table.
      - `variant_name` string — The name of the product variant. Maps to `products_info.variant_name` in the Orders table.
      - `sku` string — The stock keeping unit of the product. Maps to `products_info.product_sku` in the Orders table.
    - `name` string — 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.
    - `payment_gateway_names` string[] — 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.
    - `refunds` object[] — Details of refunds applied to the order.
      - `refund_id` string, required — The unique identifier for the refund.
      - `refunded_at` string, date-time, required — 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`).
      - `line_items` object[] — Details of refunded line items.
        - `id` string, required — The unique identifier for the refunded line item.
        - `line_item_id` string — The unique identifier of the line item associated with this refund line item.
        - `quantity` integer, required — The quantity of the refunded line item.
        - `product_id` string — The unique identifier for the refunded product.
        - `variant_id` string, required — The unique identifier for the refunded variant.
        - `price` number, required — The price of the refunded line item.
        - `currency` string — The currency of the refunded line item.
        - `total_discount` number — The total discount applied to the refunded line item.
      - `total_refund` number, required — The total amount refunded.
      - `total_tax_refund` number — The total tax refunded.
      - `total_shipping_refund` number — The total shipping refunded.
      - `tags` string[] — Tags associated with the refund.
      - `void` boolean — 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)
    - `shipping_address` object — Shipping address details.
      - `address_1` string — The first line of the address.
      - `address_2` string — The second line of the address.
      - `zip` string — The ZIP or postal code of the address.
      - `city` string — The city of the address. Maps to `customer_from_city` in the Orders table.
      - `country` string — The country of the address.
      - `country_code` string — The country code of the address. Maps to `customer_from_country_code` in the Orders table.
      - `province_code` string — The province or state code of the address. Maps to `customer_from_state_code` in the Orders table.
    - `shipping_lines` object[] — Details of the shipping lines for the order.
      - `shipping_discounted_price` number — The discounted price for shipping.
      - `shipping_price` number — The original price for shipping.
      - `source` string — The source or method of shipping.
      - `title` string — The title or description of the shipping method.
    - `shipping_price` number — The total shipping price of the order (paid by the buyer), including shipping taxes and shipping discounts.
    - `shipping_costs` number — 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.
    - `source_name` string — The origin of the order as designated by the seller on the main sales platform (e.g. `web`, `pos`, `tiktok`).
    - `subscription_id` string — The unique identifier for the subscription associated with the order.
    - `tags` string[] — 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.
    - `taxes_included` boolean — Indicates if taxes are included in the total price of the order.
    - `order_revenue` number, required — The total revenue after adjustments such as discounts, shipping, fees, and taxes. Must be non-negative.
    - `total_discounts` number — The total discount amount applied to the order, including shipping discounts. Must be non-negative. Maps to `discount_amount` in the Orders table.
    - `taxes` number — The total tax applied to the order. Must be non-negative.
    - `status` string — The current status of the order (e.g., "completed", "pending"). Maps to `fulfillment_status` in the Orders table.
    - `updated_at` string, date-time — 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.
    - `void` boolean — 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)

## Response `200`

Order records successfully received.

- object
  - `success` boolean
  - `message` string

## Other responses

- `400` — Bad Request. Returned if one or more orders fail validation. Valid orders in the same request are still processed even when this response is returned.
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/triplewhale/apis/triple-whale-api.md) · [All operations](https://skmtc.net/triplewhale/apis/triple-whale-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/triplewhale/triple-whale-api/versions/96b22ac9b5a7/schema)