v1

latestOpenAPI 3.1.02026-08-04170116.0 KB

Data In

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.

post/data-in/orders

Request body

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

order_idstring required

The unique identifier for the order.

platformstring

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_idstring

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

currencystring required

The currency in which the transaction was processed (e.g. USD, EUR).

custom_expensesnumber

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

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

namestring

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_namesstring[]

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.

shipping_pricenumber

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

shipping_costsnumber

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.

source_namestring

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

subscription_idstring

The unique identifier for the subscription associated with the order.

tagsstring[]

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_includedboolean

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

order_revenuenumber required

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

total_discountsnumber

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

taxesnumber

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

statusstring

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

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

voidboolean

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

Example request

{
  "shop": "madisonbraids.myshopify.com",
  "order_id": "order_12345",
  "platform": "magento",
  "platform_account_id": "shop_account_123",
  "created_at": "2022-06-15T19:26:30.000Z",
  "currency": "USD",
  "customer": {
    "id": "customer_123",
    "email": "customer@example.com",
    "phone": "+1234567890",
    "first_name": "John",
    "last_name": "Doe"
  },
  "custom_expenses": 25,
  "is_new_customer": true,
  "discount_codes": [
    {
      "code": "BLACKFRIDAY",
      "amount": 15.5,
      "type": "percentage"
    }
  ],
  "line_items": [
    {
      "id": "line_item_1",
      "name": "Line Item 1",
      "price": 20,
      "quantity": 2,
      "product_id": "product_123",
      "product_name": "T-shirt",
      "variant_id": "variant_456",
      "variant_name": "Red T-shirt (Large)",
      "sku": "sku_123"
    }
  ],
  "name": "Order #12345",
  "payment_gateway_names": [
    "paypal"
  ],
  "refunds": [
    {
      "refund_id": "refund_1",
      "refunded_at": "2024-11-29T11:00:00Z",
      "line_items": [
        {
          "id": "line_item_1",
          "line_item_id": "line_item_1",
          "quantity": 1,
          "product_id": "product_123",
          "variant_id": "variant_456",
          "price": 20,
          "currency": "USD"
        }
      ],
      "total_refund": 40,
      "total_tax_refund": 3,
      "total_shipping_refund": 5,
      "tags": [
        "damaged_item"
      ]
    }
  ],
  "shipping_address": {
    "address_1": "123 Main Street",
    "address_2": "Apt 4B",
    "zip": "10001",
    "city": "New York",
    "country": "USA",
    "country_code": "US",
    "province_code": "NY"
  },
  "shipping_lines": [
    {
      "shipping_discounted_price": 5,
      "shipping_price": 10,
      "source": "standard_shipping",
      "title": "Standard Shipping"
    }
  ],
  "shipping_price": 15,
  "shipping_costs": 15,
  "source_name": "web",
  "subscription_id": "sub_12345",
  "tags": [
    "holiday_sale",
    "staff_order"
  ],
  "order_revenue": 150.75,
  "total_discounts": 15.5,
  "taxes": 8.25,
  "status": "completed",
  "updated_at": "2024-11-29T10:00:00Z"
}

Response

Order record successfully received.

successboolean

messagestring

Example response

{
  "success": true,
  "message": "Order received"
}