API & SDK Reference

Bulk Create Order Records

post
https://api.triplewhale.com/api/v2/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.

📘

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.

Body Params
string
required

The exact Shop URL (e.g., 'example.myshopify.com'). Must match the Shop URL value shown in Settings → Store. 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
array of objects
required
length between 1 and 1000

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).

orders*
string

Optional. If provided, it will be overwritten by the top-level shop value in this request.

string
required

The unique identifier for the order.

string
Defaults to custom-msp

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.

string
Defaults to custom-msp

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.

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.

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.

number

Custom expenses associated with the order, must be non-negative.

boolean | null

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
array of objects

Discount codes applied to the order.

discount_codes
line_items
array of objects

Details of the products in the order.

line_items
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
array of strings

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 > Gateway Costs.

payment_gateway_names
refunds
array of objects

Details of refunds applied to the order.

refunds
shipping_address
object

Shipping address details.

shipping_lines
array of objects

Details of the shipping lines for the order.

shipping_lines
number

The total shipping price of the order (paid by the buyer), including shipping taxes and shipping discounts.

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 > Shipping.

string

The origin of the order as designated by the seller on the main sales platform (e.g. web, pos, tiktok).

string

The unique identifier for the subscription associated with the order.

tags
array of strings

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.

tags
boolean
Defaults to false

Indicates if taxes are included in the total price of the order.

number
required

The total revenue after adjustments such as discounts, shipping, fees, and taxes. Must be non-negative.

number

The total discount amount applied to the order, including shipping discounts. Must be non-negative. Maps to discount_amount in the Orders table.

number

The total tax applied to the order. Must be non-negative.

string

The current status of the order (e.g., "completed", "pending"). Maps to fulfillment_status in the Orders table.

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.

boolean
Defaults to false

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

Responses

Updated 20 days ago

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 20 days ago