A product represents a service or item that a merchant sells through an XPay subscription. Create products before creating a plan.
For complete field definitions and response schemas, see the XPay API reference.
Product operations
Create a product
XPay amounts use major currency units and support up to two decimal places. For example, 5000 with PKR represents PKR 5,000.00, and 5000.50 represents PKR 5,000.50.
POST {{base_url}}/public/v1/product
{
"name": "LedgerPro Basic",
"description": "Monthly access to LedgerPro Basic",
"price": 5000,
"currency": "PKR",
"active": true,
"features": [
"Core accounting",
"Standard reporting"
]
}The response returns the created product in data:
{
"success": true,
"responseStatus": "OK",
"message": "Request processed successfully.",
"data": {
"product_id": "xpay_product_{{product_id}}",
"name": "LedgerPro Basic",
"description": "Monthly access to LedgerPro Basic",
"price": 5000,
"currency": "PKR",
"active": true,
"features": [
"Core accounting",
"Standard reporting"
]
}
}The response is shortened to the fields used in the subscription flow.
Required fields:
name: Merchant-facing product name.price: Unit price. The value must be at least1.currency: Supported three-letter currency code.
XPay generates the product ID when id is omitted. If the merchant supplies id, store and use the returned product_id in later requests.
Use products in a plan
A plan's product array contains items with a product ID and quantity:
{
"product": [
{
"product_id": "{{product_id}}",
"quantity": 1
}
]
}When plan-level amount and currency are omitted, XPay calculates the plan amount from the referenced product prices and quantities. All referenced products must be active. When a plan contains multiple products and derives its amount from them, the products must use the same currency.
Supplying plan-level amount and currency sets the plan's billing amount independently of the calculated product total.
Create another subscription tier
Create a separate product for each independently priced subscription tier. For LedgerPro Plus:
{
"name": "LedgerPro Plus",
"description": "Monthly access to LedgerPro Plus",
"price": 8000,
"currency": "PKR",
"active": true,
"features": [
"Priority support",
"Advanced reporting"
]
}Store the Plus product ID separately from the Basic product ID. The merchant uses each product ID in its corresponding plan rather than renaming one product when a customer changes tiers.
Update a product
{
"name": "LedgerPro Basic",
"description": "Monthly access to LedgerPro Basic with updated reporting",
"price": 5500,
"currency": "PKR"
}Updating a product doesn't automatically change the price stored on an existing subscription. Use Manage a fixed-price subscription when a merchant intends to change an existing customer's quantity or price.
Store for reconciliation
Store the following values:
product_id- Product name
- Price and currency
- Active state
- Related plan IDs