Skip to guide
Podyx Developers Studio API v2

STUDIO API / CAPABILITY GUIDES

Read Markdown ↗

Manage promo codes and client credits

Create one code per partner, record its ID and reconcile redemptions through the order lists. If a sale qualifies for a referral reward, add credit to the partner's Client wallet. Order reads and referral reconciliation

Manage partner codes

GET /api/v2/promo-codes lists configured codes in code order. Pass status=active or status=inactive to filter the list. The status uses the same active or inactive classification as the CMS, including expiry. Use page and per_page to paginate. GET /api/v2/promo-codes/{id} returns one code, including inactive codes. Both reads require promo_codes:read. Promo-code list

POST /api/v2/promo-codes creates a code and returns 201, a Location header and the stable resource_id. Set discount_type to percentage or fixed and send discount_value as a decimal string. For a percentage, "10" means ten percent. For a fixed discount, "10" means ten units of studio currency. valid_from and valid_until are ISO 8601 timestamps. Configure max_uses, per_user_limit, and the allowed purchase kinds, setups, services or bundle plans as needed. Set client_id to restrict the code to one current Client. Create a promo code

PATCH /api/v2/promo-codes/{id} changes only supplied settings. An empty scope list removes that restriction. client_id: null clears a Client restriction. Set is_active: false to deactivate the code. Its history remains readable. Create requires promo_codes:create and update requires promo_codes:update. Both imply promo_codes:read. Update a promo code

Configure Specific add-ons on the studio's CMS promo-code form. Matching paid add-ons can receive the discount on a booking quote and in the client portal's Additional Services checkout. Updates through the promo management API preserve the CMS add-on selection.

Adjust a Client wallet

GET /api/v2/clients/{id}/credits returns the current balance and studio currency. GET /api/v2/clients/{id}/credit-ledger returns a paginated history, newest first, including each entry's signed amount, balance after the entry and note where recorded. An older entry can have a null currency if the currency was not recorded on the entry. These reads require credits:read. Client credit ledger

POST /api/v2/clients/{id}/credit-adjustments requires credits:adjust and its implied credits:read. Send direction as add or remove, a positive decimal string in studio currency and a note of up to 500 characters. A removal cannot exceed the available balance. Adds use the same per-adjustment limit as the CMS. The response is 201 with the committed ledger entry. Add or remove client credit

Retry writes

Send a UUID Idempotency-Key with each promo or credit write. Keep the key with the intended change. Retrying the same command under the same API key returns the original resource ID or credit ledger entry, with replayed: true. The credit entry retains its original balance after the adjustment. A different normalized command under the same key and operation returns 409 idempotency_conflict. If another request still holds the key, 409 request_in_progress means you can retry the original command with the same key.