Packages

Prepaid credit bundles you can sell on behalf of a customer, then optionally consume at confirm (use_package_credit: true). Confirm only ever uses credits from packages you sold. A package the customer bought at the venue or through another channel is never used.

Auth: x-api-key. idempotency_key is required on purchase.

Purchase

POST /api/v1/packages/{packageId}/purchase
Content-Type: application/json
x-api-key: <your-api-key>

{
  "customer_phone": "9876543210",
  "payment_method": "upi",
  "idempotency_key": "pkg-9f2a-…"
}

201: { "purchase": { "id", "package_id", "customer_phone", "credits_remaining", … } }.

Same key, same package and customer → original purchase, no extra credits. Same key, different customer or package → 409.

A package at a venue your key is not granted answers 404, exactly like an unknown package id.

There is no partner call that lists a venue's packages. VenueSetu gives you the package ids you may sell, per venue, during onboarding. Sandbox package id: a0000000-0000-4000-8000-000000000003.

Get a purchase

GET /api/v1/packages/purchases/{purchaseId}
x-api-key: <your-api-key>

Active purchases

GET /api/v1/packages/active?customer_phone=9876543210&venue_id=<uuid>
x-api-key: <your-api-key>

Both query parameters are required. A venue your key is not granted → 403 VENUE_NOT_AUTHORIZED.

Paying with a package credit

Send use_package_credit: true on POST /bookings/confirm instead of collecting a payment.

• Success (201): one credit is deducted from an active package you sold to this customer at this venue, in the same transaction as the booking, and the response carries package_credit_consumed: true. If the customer has several of your packages, the one that expires first is used.
• No eligible credit (409 PACKAGE_CREDIT_UNAVAILABLE): nothing is booked and nothing is deducted. Packages bought at the venue, on the VenueSetu storefront or through another partner never count. The hold stays active until its hold_expiry_at, so you can still:
  • sell the customer a package (POST /packages/{packageId}/purchase), then confirm again with use_package_credit: true; or
  • take payment and confirm without use_package_credit; or
  • release the hold.
• Retries: a refusal is not stored against your idempotency_key, so you may confirm again with the same key once you have fixed the cause. A confirm that succeeded replays its original result, including package_credit_consumed: true, and never deducts a second credit.
• Concurrency: if two confirms race for a customer's last credit, one books and the other gets PACKAGE_CREDIT_UNAVAILABLE.