Order2

Properties

• idstringrequired

  ID of the order in the ecommerce system

  Example: "123456789"

• order_timetimeoptional

  The time the order has been placed in the ecommerce system

  This value is the primary timestamp of the order, used both for analytics (attributing revenues to a particular day) and for important user-visible purposes like determining which time-based point multiplier promos are applicable.

  An ideal value is the time when the order has been submitted or confirmed by the customer. Depending on how your ecommerce is built, it might or might not match the creation time of an order object in your system..

  Example: "2022-05-01T11:22:33Z"

• update_timetimeoptional

  The last time the order information has been updated in any relevant way

  This value is used for auxiliary purposes, like sorting order data by last update time. (Also, when doing pull-based order processing, Bubblehouse queries for new orders based on this field.)

  Example: "2022-05-02T20:10:00Z"

• statusOrderStatus2optional

  Whether the order has been paid, shipped, refunded, etc.

  Example: "confirmed"

• customerCustomer2required

  Information about the customer placing the order

  You can either pass a customer identity (i.e. an object with a single id or email property) to reference an existing customer, or a full customer object to create/update the customer as well.

  When referencing an existing customer, id is much preferred over email to avoid edge cases.

  Example: {"id":"123456789"}

• itemsarray of OrderItem2optional

  Information about the ordered products

  Example: [{"id":"xyz101","product":{"id":"P123","title":"Supershoe","collection_ids":["C42","C1"]},"quantity":2,"amount_full":"12.00","amount_spent":"8.00"},{"id":"xyz102","product":{"id":"P124","title":"Megashoe","collection_ids":["C42"]},"quantity":1,"amount_full":"20.00","amount_spent":"20.00"}]

• discount_codesarray of stringoptional

  A list of discount codes applied to this order

  Bubblehouse uses discount codes found on orders to track redeeming of points, usage of benefits, and to track referrals.

  It's okay to only provide discount codes that originate from Bubblehouse; we don't need to know about other codes. (But it's also okay to provide all discount codes; we'll ignore the ones we did not create.)

  Example: ["AB12345CDEF","FRIEND-123456"]

• store_locationstringoptional

  A unique identifier of a particular store location where the order has been made

  This is a niche field only relevant for enabling rewards based on specific store locations visited.

• amount_fullmonetaryrequired

  Full (undiscounted) amount of the order that should be attributed to this customer for analytics.

  Example: "300.00"

• amount_spentmonetaryrequired

  Amount actually spent by the customer (taking into account all possible costs, discounts and other price adjustments).

  Example: "250.00"

• shortstringoptional

  A short, human-readable identifier for the order

  This is typically an order number like "#1234" or "ORD-5678" that customers see. If not provided, Bubblehouse will use the order ID as a fallback.

  Example: "R-789"

• amount_subtotalmonetaryoptional

  The subtotal of all items before discounts, taxes, and shipping

  While optional, it's best to provide this along with amount_spent and amount_full for optimal discount allocation and analytics.

  Example: "280.00"

• amount_discountsmonetaryoptional

  Total amount of discounts applied to the order

  This helps with proper allocation of order-level discounts across line items.

  Example: "50.00"

• amount_refundedmonetaryoptional

  Total amount refunded to the customer

  Providing this separately helps with proper allocation of order-level discounts across line items.

  Example: "0.00"

• amount_taxesmonetaryoptional

  Total tax amount on the order

  Providing this separately helps with proper allocation of order-level discounts across line items, and allows to exclude taxes from loyalty point calculations.

  Example: "15.00"

• amount_shippingmonetaryoptional

  Total shipping costs for the order

  Providing this separately helps with proper allocation of order-level discounts across line items, and allows to exclude shipping from loyalty point calculations.

  Example: "5.00"

• amount_redeemed_at_checkoutmonetaryoptional

  Dollar value of points redeemed directly at checkout

  This field represents the monetary value of loyalty points that were redeemed directly during the checkout process, rather than through discount codes. This is used for direct redemption functionality where customers can apply points as payment.

  Mutually exclusive with pts_redeemed_at_checkout. Provide either this field (and Bubblehouse will calculate the points) or pts_redeemed_at_checkout (and Bubblehouse will calculate the amount), but never both. If both are provided, pts_redeemed_at_checkout takes precedence.

• pts_redeemed_at_checkoutintegeroptional

  Number of loyalty points redeemed directly at checkout

  This field represents the exact number of loyalty points that were redeemed directly during the checkout process. This is used for direct redemption functionality where customers can apply points as payment.

  Mutually exclusive with amount_redeemed_at_checkout. Provide either this field (and Bubblehouse will calculate the dollar value) or amount_redeemed_at_checkout (and Bubblehouse will calculate the points), but never both. If both are provided, this field takes precedence.

• is_subscriptionbooleanoptional

  Whether this order is part of a subscription

  Subscription orders may have different point accrual rules or timing compared to regular orders.

• store_typeStoreType2optional

  The type of store where the order was placed

  This helps with analytics and also allows for different point accrual rules based on where customers shop. Defaults to online if not specified.

  Example: "online"

• tagsarray of stringoptional

  Arbitrary tags associated with the order

  These can be used to pass additional metadata about the order that may be specific to your store's situation. Tags can be used in conditions for rewards and promotions.

• extrasJSON object (string keys and arbitrary values)optional

  Any additional data you want to associate with the order

  Extras can be used to pass additional metadata about the order that may be specific to your store's situation. Similar to tags but for structured data. This allows passing custom information that may be needed for your specific integration or business logic.

• fulfillmentsarray of OrderFulfillment2optional

  Information about order fulfillments (shipments)

  Providing fulfillment data allows Bubblehouse to optionally delay point accrual until items are fulfilled or delivered. This is essentially shipment tracking information.

  If you provide this field, please also provide fulfillment_status.

  Example: [{"id":"flf201","items":[{"id":"xyz101","qty":2}],"delivered":false}]

• fulfillment_statusFulfillmentStatusoptional

  Overall fulfillment status of the order

  You can provide no fulfillment information at all, or you can provide order-level fulfillment_status only, or both fulfillment_status and fulfillments.

  Including fulfillment_status in addition to fulfillments ensures Bubblehouse can tell when the entire order has been fulfilled, in case certain items do not require fulfillment.

  Example: "partial"

• deletedbooleanoptional

  Set to true to delete this order in our system

  Bubblehouse does not have deletion APIs for most objects; instead, pass deleted: true when updating an object. Note that we won't delete the data immediately, in case there are other objects referencing this one.

  Deleting an order is the same as setting its status to deleted, which is about the same as canceled.

Examples

{
  "id": "123456789",
  "short": "R-789",
  "order_time": "2022-05-01T11:22:33Z",
  "update_time": "2022-05-02T20:10:00Z",
  "status": "confirmed",
  "customer": {
    "id": "123456789"
  },
  "amount_full": "300.00",
  "amount_subtotal": "280.00",
  "amount_spent": "250.00",
  "amount_discounts": "50.00",
  "amount_refunded": "0.00",
  "amount_taxes": "15.00",
  "amount_shipping": "5.00",
  "store_type": "online",
  "items": [
    {
      "id": "xyz101",
      "product": {
        "id": "P123",
        "title": "Supershoe",
        "collection_ids": [
          "C42",
          "C1"
        ]
      },
      "quantity": 2,
      "amount_full": "12.00",
      "amount_spent": "8.00"
    },
    {
      "id": "xyz102",
      "product": {
        "id": "P124",
        "title": "Megashoe",
        "collection_ids": [
          "C42"
        ]
      },
      "quantity": 1,
      "amount_full": "20.00",
      "amount_spent": "20.00"
    }
  ],
  "fulfillments": [
    {
      "id": "flf201",
      "items": [
        {
          "id": "xyz101",
          "qty": 2
        }
      ],
      "delivered": false
    }
  ],
  "fulfillment_status": "partial",
  "discount_codes": [
    "AB12345CDEF",
    "FRIEND-123456"
  ]
}

{
  "id": "123456789",
  "order_time": "2022-05-01T11:22:33Z",
  "customer": {
    "id": "123456789"
  },
  "amount_full": "300.00",
  "amount_spent": "250.00"
}

{
  "id": "123456789",
  "order_time": "2022-05-01T11:22:33Z",
  "customer": {
    "id": "123456789"
  }
}