AddProductToSubscription1

Add a loyalty reward product to a customer's subscription.

Subscribe to this hook from Hello1 when your custom subscription platform can add free or discounted reward products to a specific subscription.

Bubblehouse may call this hook during a customer redemption or while delivering a subscription milestone reward. Return added: true only after confirming the product was added. An unsuccessful direct redemption falls back to the configured customer redemption path. A milestone response with added: false and retry: true schedules another delivery attempt.

Use the subscription-system subscription_id as the primary lookup key. The product and variant use the same normalized payloads as Bubblehouse first-party integrations and Order API data.

The contract does not provide one stable idempotency key across separate delivery attempts. A later attempt is a new hook invocation and can have a different X-Request-ID. Before advertising this hook, ensure your platform can reconcile an ambiguous failure without creating an unintended duplicate line.

Input

• customer CustomerIdentity1 required

  Customer who owns the subscription.

• subscription_id string required

  Stable primary subscription ID assigned by the subscription system.

• subscription_ecomm_id string optional

  Distinct ID assigned to the same subscription by a separate ecommerce system.

• destination RedeemDestination1 optional

  Optional provider-specific destination selected by the customer.

• product Product2 required

  Product to add.

• variant ProductVariant2 required

  Specific product variant to add.

• price monetary required

  Final unit price requested for the added line. Zero means free.

• discount_bp permyriad optional

  Percentage discount in basis points when the provider applies a percentage-based adjustment.

Output

• added boolean required

  Whether the product was added successfully.

• retry boolean optional

  Whether retrying may succeed after an unsuccessful attempt.

• subscription_line_id string optional

  Stable ID of the created subscription line in the subscription system.

• debug_info string optional

  Diagnostic details for Bubblehouse operators. Do not include secrets or unnecessary customer data.

{
  "customer": {
    "email": "alice@example.com",
    "shopid": "CUSTOMER-501"
  },
  "destination": {},
  "discount_bp": 0,
  "price": "0.000000",
  "product": {
    "id": "PRODUCT-301",
    "title": "Example product"
  },
  "subscription_ecomm_id": "ECOMM-SUB-1001",
  "subscription_id": "SUB-1001",
  "variant": {
    "id": "VARIANT-401",
    "price": "20.000000",
    "title": "Example variant"
  }
}

{
  "added": true,
  "subscription_line_id": "SUB-LINE-9001"
}