Order API

Type

Order2

Represents a single customer order that Bubblehouse takes in.

Orders are the primary way customers earn loyalty points. This page covers what data to provide, from the bare minimum to full detail that enables advanced features like stable per-item refunds.

Order data

Required fields

Only two things are truly required:

  • Order ID (id) uniquely identifies the order
  • Some unique customer identifier — for example, customer.id or customer.email

Everything else is optional but enables more features.

Order-level data

  • id, customer enable order tracking
  • status controls eligibility timing and later state transitions; omitted or unknown status on a new order defaults to confirmed; amount_spent and/or amount_subtotal enable point accrual
  • order_time enables more accurate timestamps for orders in the face of processing delays
  • amount_discounts enables discount allocation
  • amount_taxes, amount_shipping enables tax/shipping exclusion
  • billing_address, shipping_address enable address-based referral fraud detection

Line item data

Line items (items) are optional but enable:

  • Per-item refunds with accurate point adjustment
  • Rewards based on purchasing specific products
  • Excluding specific products from earning points
  • Product-based analytics

Line item amounts

  • product, quantity enable rewards based on purchase counts, and disallowing accrual on certain products
  • amount_spent and/or amount_full enables per-item point accrual
  • amount_discount helps with stable discount allocation (see Advanced refunds)

Fulfillments (aka shipments)

Fulfillment data (fulfillments, fulfillment_status) is optional but enables delaying point accrual until items ship or are delivered.

Point accrual

Points are calculated from amount_spent by default, although we can configure additional options internally. If you also provide amount_taxes and amount_shipping, those can be excluded from point calculation (based on your store configuration).

Gift card payments

Most API integrations should omit gift_cards_used and gift_card_uses_known. Provide them only when your platform can report order payment transactions paid by gift card.

When provided, gift_cards_used is a payment ledger: captures are positive rows, refunds are negative rows. Set gift_card_uses_known: true only when the ledger is complete for the order; an empty ledger with this flag set means known zero gift-card payment.

Shipping discounts

Most integrations should not send shipping-discount fields. If your platform already reports final paid totals in a straightforward way, send amount_spent, amount_discounts, and amount_shipping as you normally would and omit the fields below.

Use amount_shipping_discount only for the uncommon shape where a shipping discount is included in amount_discounts, but amount_shipping still contains the pre-discount shipping charge. In that case, also set is_shipping_discount_included_in_total_discount: true.

Simple refunds

For typical refund scenarios, simply update the order with reduced amounts:

  1. Reduce amount_spent to the post-refund value
  2. Reduce amount_subtotal proportionally
  3. For line item refunds: reduce quantity and amounts on affected items

Bubblehouse recalculates points based on the new amounts. This works well when:

  • There are no order-level discounts, or
  • You don't need per-item point stability after partial refunds

Simple refund example

// Original order: $100 spent
{
  "id": "ORD-001",
  "status": "confirmed",
  "customer": { "id": "CUST-1" },
  "amount_subtotal": "100.00",
  "amount_spent": "100.00",
  "items": [
    { "id": "item-1", "product": { "id": "A" }, "quantity": 2, "amount_full": "50.00", "amount_spent": "50.00" },
    { "id": "item-2", "product": { "id": "B" }, "quantity": 1, "amount_full": "50.00", "amount_spent": "50.00" }
  ]
}

// After refunding 1 unit of item-1 ($25):
{
  "id": "ORD-001",
  "status": "confirmed",
  "customer": { "id": "CUST-1" },
  "amount_subtotal": "75.00",
  "amount_spent": "75.00",
  "items": [
    { "id": "item-1", "product": { "id": "A" }, "quantity": 1, "amount_full": "25.00", "amount_spent": "25.00" },
    { "id": "item-2", "product": { "id": "B" }, "quantity": 1, "amount_full": "50.00", "amount_spent": "50.00" }
  ]
}

Advanced refunds

When an order has order-level discounts (like "20% off your order"), Bubblehouse allocates these discounts proportionally across line items. This allocation affects how many points each item earns and, thus, how many points are refunded for that item.

When you refund one item, the proportions change, causing reallocation of order-level discounts. This can cause small point adjustments on items that weren't refunded - leading to customer support complaints about "incorrect" refunds.

Example: unstable allocation

// Original: $100 subtotal, $20 order discount, $80 spent
// Discount allocated: Item A gets $10, Item B gets $10
// Points earned: Item A = 40 pts, Item B = 40 pts

// After fully refunding Item B (simple approach):
// Now only Item A remains at $50 subtotal
// The $20 discount is reallocated entirely to Item A
// Item A now shows: $50 - $20 = $30 spent = 30 pts
// Customer lost 10 points on Item A even though it wasn't refunded!

Allocation stability solutions

Best solution: Provide line-item discounts (amount_discount) that sum to the order discount (amount_discounts). When line item discounts cover the order discount, no allocation happens - the values you provide are used directly.

// Original order with explicit line discounts:
{
  "id": "ORD-002",
  "status": "confirmed",
  "customer": { "id": "CUST-1" },
  "amount_subtotal": "100.00",
  "amount_discounts": "20.00",
  "amount_spent": "80.00",
  "items": [
    {
      "id": "item-1",
      "product": { "id": "A" },
      "quantity": 1,
      "amount_full": "50.00",
      "amount_discount": "10.00",  // Explicit: $10 of the $20 order discount
      "amount_spent": "40.00"
    },
    {
      "id": "item-2",
      "product": { "id": "B" },
      "quantity": 1,
      "amount_full": "50.00",
      "amount_discount": "10.00",  // Explicit: $10 of the $20 order discount
      "amount_spent": "40.00"
    }
  ]
}

// After refunding Item B - reduce order discount proportionally:
{
  "id": "ORD-002",
  "status": "confirmed",
  "customer": { "id": "CUST-1" },
  "amount_subtotal": "50.00",
  "amount_discounts": "10.00",    // Reduced from $20 to $10
  "amount_spent": "40.00",
  "items": [
    {
      "id": "item-1",
      "product": { "id": "A" },
      "quantity": 1,
      "amount_full": "50.00",
      "amount_discount": "10.00",  // Unchanged - stable!
      "amount_spent": "40.00"      // Unchanged - 40 pts still
    },
    {
      "id": "item-2",
      "product": { "id": "B" },
      "quantity": 0,              // Fully refunded
      "amount_full": "0.00",
      "amount_discount": "0.00",
      "amount_spent": "0.00"
    }
  ]
}

Also possible: If amount_discount of line items is not provided or adds up to less than the order discount, the remaining discount is allocated by Bubblehouse proportionally. Provide all supported amount fields on the order and line items to help Bubblehouse make this allocation as stable as possible.

Allocation stability matters when 3 conditions mix:

  • Orders with order-level discounts (coupons, automatic discounts)
  • Partial refunds of multi-item orders
  • You require exact, predictable point adjustments when doing these refunds

This entire section does not matter for:

  • Orders without discounts
  • Full order cancellations
  • Single-item orders
Kind Type
Used in Cart2, EstimateAccrual1, LoadCart1, UpdateOrders4

Properties

  • id string required

    ID of the order in the ecommerce system

  • order_time time optional

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

  • update_time time optional

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

  • status OrderStatus2 optional

    Whether the order has been confirmed, completed, or canceled.

    New stores require confirmed or completed status before an order earns points, contributes loyalty spend, or satisfies product conditions.

    Send the current status whenever your system knows it. When creating an order, an omitted or unknown status is treated as confirmed.

    When updating an existing order, an omitted or unknown status preserves the stored status. Send an explicit known status when it changes.

  • customer Customer2 required

    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.

  • items array of OrderItem2 optional

    Information about the ordered products

  • discount_codes array of string optional

    A list of coupon codes applied to this order

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

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

  • discount_uses array of OrderDiscountUse2 optional

    Cumulative per-code discount application and refund amounts

    Most integrations should omit this field.

    Provide it when your commerce platform can attribute the original applied discount and cumulative refunded discount to each exact code. Bubblehouse uses this data to return only the redeemed points associated with the refunded portion of a Bubblehouse code.

  • discount_uses_known boolean optional

    Whether discount_uses is complete for the order

    Set to true only when discount_uses covers every code allocation relevant to the order and all finalized refunds.

    If omitted or false, Bubblehouse treats per-code refund attribution as unknown and does not estimate partial redeemed-point refunds. Explicit full order cancellation still returns the remaining redeemed points.

  • store_location string optional

    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_full monetary required

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

  • amount_spent monetary required

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

  • short string optional

    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.

  • amount_subtotal monetary optional

    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.

  • amount_discounts monetary optional

    Total amount of discounts applied to the order

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

  • amount_refunded monetary optional

    Total amount refunded to the customer

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

  • amount_taxes monetary optional

    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.

  • amount_shipping monetary optional

    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.

  • amount_shipping_discount monetary optional

    Shipping-specific discount amount, for platforms that include shipping discounts in total discounts

    Most clients should omit this field.

    Use this only when a shipping discount is included in amount_discounts, but amount_shipping still reports the pre-discount shipping amount.

    When sending this field for that shape, also set is_shipping_discount_included_in_total_discount: true.

  • is_shipping_discount_included_in_total_discount boolean optional

    Whether amount_shipping_discount is already included in amount_discounts

    Set this to true only when amount_shipping_discount is a subset of amount_discounts, not an additional discount.

  • payment_methods array of string optional

    Payment method identifiers used on the order

    Use normalized values when possible, for example gift_card.

  • gift_cards_used array of OrderGiftCardUse1 optional

    Gift-card payment ledger rows for this order

    Most API integrations should omit this field.

    When your platform can report gift-card payment transactions, send one row per relevant payment transaction. Captures should use positive amounts and refunds should use negative amounts.

    The first successful capture whose gift_card_ext_id matches a pending gift-card coupon code_id consumes that redemption.

  • gift_card_uses_known boolean optional

    Whether gift_cards_used is complete for the order

    Set to true only when your integration has inspected payment transactions and gift_cards_used contains every gift-card payment row for the order.

    If this is omitted or false, Bubblehouse treats gift-card payment data as unknown rather than zero.

  • direct_redemption_known boolean optional

    Whether the direct-redemption fields are authoritative for this order

    Set to true when your integration has inspected direct checkout redemption data and the current values of amount_redeemed_at_checkout and pts_redeemed_at_checkout are complete.

    This flag is required to authoritatively report that a previous direct redemption is now zero. If this is omitted or false and both redemption values are zero, Bubblehouse treats the direct-redemption data as unknown and preserves the stored value.

  • amount_redeemed_at_checkout monetary optional

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

    A nonzero value is treated as known for backward compatibility. Set direct_redemption_known: true when reporting an authoritative zero.

  • pts_redeemed_at_checkout integer optional

    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.

    A nonzero value is treated as known for backward compatibility. Set direct_redemption_known: true when reporting an authoritative zero.

  • is_subscription boolean optional

    Whether this order is part of a subscription

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

  • store_type StoreType2 optional

    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.

  • tags array of string optional

    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.

  • extras JSON 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.

  • fulfillments array of OrderFulfillment2 optional

    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.

  • fulfillment_status FulfillmentStatus optional

    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.

  • deleted boolean optional

    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.

  • billing_address PostalAddress1 optional

    Billing address for this order

    Providing billing address data enables address-based referral fraud detection, where Bubblehouse can block referral rewards when the referee's billing address matches addresses from other customers' orders or customer profiles.

    Address processing must be enabled in your store's settings before address data is stored. If billing address processing is not enabled, this field is silently ignored.

    Important: For address matching to work, the address must include address1, city, and country_code (ISO 3166-1 alpha-2, e.g. "US", "CA"). The country field is for display only and is not used in matching.

  • shipping_address PostalAddress1 optional

    Shipping address for this order

    Providing shipping address data enables address-based referral fraud detection, where Bubblehouse can block referral rewards when the referee's shipping address matches addresses from other customers' orders or customer profiles.

    Address processing must be enabled in your store's settings before address data is stored. If shipping address processing is not enabled, this field is silently ignored.

    Important: For address matching to work, the address must include address1, city, and country_code (ISO 3166-1 alpha-2, e.g. "US", "CA"). The country field is for display only and is not used in matching.

  • market MarketInput1 optional

    Market context for this order

    Provide this when your commerce platform can identify the storefront market, locale, country, currency, or market key used for the order.

    Bubblehouse resolves the input to a configured market when possible and stores that market on the order for future loyalty behavior. If the input is missing or ambiguous, the order uses the store's default/global behavior.

Previous
ObjectIdentity1
Next
OrderDiscountUse2