How to Integrate Promo Credit for Customers via OpenAPI

​

Overview

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

• Endpoint: POST /merchant/subscription/update_submit
• Request Fields:
  • applyPromoCredit (boolean): Whether to apply promo credits.
  • applyPromoCreditAmount (number): The amount of promo credit to apply.

​

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 and connected to its invoice, and the Promo credits will be rollbacked to customer’s account when its relative invoice refund totally (partially refund will not rollback)