​
Overview

This guide explains how to integrate Promo Credits for your customers using UniBee’s OpenAPI endpoints. You will learn how to retrieve user promo credit accounts, preview subscription updates with promo credits applied, and submit subscription updates.

Note: We will also provide dedicated documentation for user-side integration of promo credits later at Promo Credits Introduction.

​
Relative API Endpoints

​
1. Get User Profile

  • Endpoint: GET /merchant/user/get
  • Important Field:
    • promoCreditAccounts: List of promo credit accounts associated with the user.

​
2. Subscription Update Preview

  • Endpoint: POST /merchant/subscription/update_preview
  • Request Fields:
    • applyPromoCredit (boolean): Whether to apply promo credits.
    • applyPromoCreditAmount (number): The amount of promo credit to apply.
  • Response Fields:
    • invoice.promoCreditAccount: The promo credit account used.
    • invoice.promoCreditPayout: Promo credit payout information.
    • invoice.promoCreditDiscountAmount: Discount amount applied using promo credit.
    • invoice.partialCreditPaidAmount: Amount partially paid using promo credits.
    • invoice.promoCreditTransaction: Transaction details related to promo credit usage.

​
3. Subscription Update Submit

​
Integration Flow

  1. Fetch User Promo Credit Information

    • Call GET /merchant/user/get to retrieve user’s promo credit accounts.

  2. Preview Subscription Update

    • Before submitting any update, call POST /merchant/subscription/update_preview with applyPromoCredit and applyPromoCreditAmount to preview the effect.
    • Review the invoice response to confirm how promo credits will be applied.

  3. Submit Subscription Update

    • Once confirmed, call POST /merchant/subscription/update_submit with the same promo credit fields to apply the changes.

​
Notes

  • Ensure that the applyPromoCreditAmount does not exceed the available balance in the user’s promo credit account.
  • Promo credits are deducted immediately upon successful subscription update submission.

For further enhancements and examples, please check Promo Credits Introduction soon!