> ## Documentation Index > Fetch the complete documentation index at: https://docs.dmly.io/llms.txt > Use this file to discover all available pages before exploring further. # Redeem a gift card against an invoice. > Draws a gift card (identified by its code) against an invoice (identified by its uuid), recording a gift_card payment that settles the invoice. An optional amount caps how much to draw; otherwise the lesser of the card balance and the invoice's amount due is applied. Responds with the redeemed amount, the card's remaining balance and the invoice's new amount due, or 422 if redemption fails. ## OpenAPI ````yaml /api-reference/openapi.json post /gift-cards/redeem openapi: 3.1.0 info: title: DMLY REST API version: 1.0.0 description: >- DMLY's public REST API — contacts/CRM, the unified inbox, broadcasts and automations, appointments and classes, the commerce catalogue, finance, webhooks and media. ## Authentication Every request carries a **workspace API key**, which both authenticates the caller and selects the workspace — so there is no workspace id in the URL. ``` x-api-key: dmly_xxxxxxxx… ``` `Authorization: Bearer dmly_xxxxxxxx…` is also accepted. Mint keys from the DMLY dashboard (Salesbot → Integrations → API), or from the CLI with `php artisan dmly:api-key create`. The plaintext key is shown **once** on creation; only its sha256 hash is stored. ## Conventions - Resources are identified by their public `uuid`, returned as `id`. - Lists are paginated with `?per_page` (alias `?limit`) — default 25, hard cap 100 — and return `{ "data": [...], "links": {...}, "meta": {...} }`. - Single resources return `{ "data": { ... } }`. ## Rate limiting **60 requests per minute, per API key.** Each key gets its own budget, so two integrations calling from the same server or office network do not compete, as long as they use separate keys. Requests without a valid key (missing, mistyped, or revoked) share one 60/minute budget per IP address instead; they fail with `401` regardless. Exceeding the limit returns `429` with a `Retry-After` header and a JSON body: `{"message": "Too many requests. Retry after 42 seconds."}`. Full detail: [Rate limits](/api-reference/rate-limits). contact: name: DMLY url: https://dmly.io servers: - url: https://dash.dmly.io/api/v1 description: DMLY security: - apiKeyAuth: [] - bearerAuth: [] tags: - name: Account description: Endpoints for Account. - name: Channels description: Endpoints for Channels. - name: Contacts description: Endpoints for Contacts. - name: Tags description: Endpoints for Tags. - name: Segments description: Endpoints for Segments. - name: Conversations & Messages description: Endpoints for Conversations & Messages. - name: Broadcasts description: Endpoints for Broadcasts. - name: Automations description: Endpoints for Automations. - name: Appointments description: Endpoints for Appointments. - name: Services & Service Categories description: Endpoints for Services & Service Categories. - name: Staff description: Endpoints for Staff. - name: Classes description: Endpoints for Classes. - name: Offerings — Products & Plans description: Endpoints for Offerings — Products & Plans. - name: Finance — Invoices description: Endpoints for Finance — Invoices. - name: Finance — Orders description: Endpoints for Finance — Orders. - name: Finance — Payments & Coupons description: Endpoints for Finance — Payments & Coupons. - name: Finance — Subscriptions description: Endpoints for Finance — Subscriptions. - name: Gift Cards description: Endpoints for Gift Cards. - name: Webhooks description: Endpoints for Webhooks. - name: Media description: Endpoints for Media. - name: Webhooks Contacts and clients description: 'Webhook events: Contacts & clients.' - name: Webhooks Conversations description: 'Webhook events: Conversations.' - name: Webhooks Calls description: 'Webhook events: Calls.' - name: Webhooks Message lifecycle description: 'Webhook events: Message lifecycle.' - name: Webhooks Appointments description: 'Webhook events: Appointments.' - name: Webhooks Classes description: 'Webhook events: Classes.' - name: Webhooks Invoices description: 'Webhook events: Invoices.' - name: Webhooks Orders description: 'Webhook events: Orders.' - name: Webhooks Payments description: 'Webhook events: Payments.' - name: Webhooks Subscriptions description: 'Webhook events: Subscriptions.' - name: Webhooks Offerings and credits description: 'Webhook events: Offerings & credits.' - name: Webhooks Store e commerce description: 'Webhook events: Store (e-commerce).' - name: Webhooks Automations description: 'Webhook events: Automations.' - name: Webhooks Broadcasts description: 'Webhook events: Broadcasts.' paths: /gift-cards/redeem: post: tags: - Gift Cards summary: Redeem a gift card against an invoice. description: >- Draws a gift card (identified by its code) against an invoice (identified by its uuid), recording a gift_card payment that settles the invoice. An optional amount caps how much to draw; otherwise the lesser of the card balance and the invoice's amount due is applied. Responds with the redeemed amount, the card's remaining balance and the invoice's new amount due, or 422 if redemption fails. operationId: giftcards.redeem.post requestBody: required: true content: application/json: schema: type: object properties: code: type: string invoice_id: type: string amount: type: integer example: code: GIFT-A1B2C3D4 invoice_id: 3c2b1a09-8f7e-6d5c-4b3a-291807060504 amount: 25 responses: '201': description: Success. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' components: responses: Unauthorized: description: The API key is missing, invalid, or its workspace no longer exists. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The workspace for this API key has been suspended, either directly or because its agency is no longer active. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: No such resource in this workspace. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ValidationError' RateLimited: description: >- Rate limit exceeded: 60 requests per minute per API key. Requests without a valid key share a per-IP budget instead. headers: Retry-After: description: Seconds until the limit resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object properties: message: type: string ValidationError: type: object properties: message: type: string errors: type: object description: Field name → array of messages. additionalProperties: type: array items: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your workspace API key. It both authenticates the caller and selects the workspace. bearerAuth: type: http scheme: bearer description: 'The same workspace API key, sent as `Authorization: Bearer `.' ````