# 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](/api/docs/guides/v2/orders)

## 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](/api/docs#/Promo%20codes/v2ListPromoCodes)

`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](/api/docs#/Promo%20codes/v2CreatePromoCode)

`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](/api/docs#/Promo%20codes/v2UpdatePromoCode)

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](/api/docs#/Client%20credits/v2ListClientCreditLedger)

`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](/api/docs#/Client%20credits/v2AdjustClientCredit)

## 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.

## Example

```sh
curl --request POST "https://app.podyx.com/api/v2/clients/$CLIENT_ID/credit-adjustments" \
  -H "Authorization: Bearer $PODYX_API_KEY" \
  -H "Idempotency-Key: $ADJUSTMENT_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"direction":"add","amount":"12.50","note":"Referral for order A123"}'
```
