Base URL
https://api.kuvert.dkAuthentication
All calls are authenticated with an API key in the Authorization header as a bearer token.
curl https://api.kuvert.dk/v1/api/giftcards \
-H "Authorization: Bearer pk_live_..."Keys are created under Settings → API keys. Only the owner can create and revoke them. There are two prefixes, and you don't choose between them:
| Prefix | Used for |
|---|---|
| pk_test_ | Testing. Does not touch real money. |
| pk_live_ | Live. Works on real cards and balances. |
Your shop sells in exactly one Stripe environment, and the key gets that environment. A demo shop gets a pk_test_ key; a shop selling for real money gets a pk_live_ key. Keys from the other environment are rejected on the first call — which is why there's no button that can choose wrong.
All calls are tied to the key's business. You cannot see or touch another business's cards, and a key only works while the business is active — a business that hasn't finished Stripe setup yet, or is suspended, gets 401.
Response format
Responses are JSON. A single gift card lives under the key giftCard, a list under giftCards.
Errors
An error always has the same shape: an object with one field called error.
{ "error": "unauthorized" }| Status | error | Means |
|---|---|---|
| 400 | invalid_issue_request | The body doesn't match what issue requires. |
| 400 | invalid_redeem_request | The body doesn't match what redeem requires. |
| 400 | bad_request | The call is missing something fundamental, typically the code in the path. |
| 400 | not_a_gift_card | The code in the path is a ticket code (TKT-…). It belongs to check-in, not a gift card — the response is 400, not 404, so you don't go looking for a card that never existed. |
| 401 | unauthorized | The key is missing, has been revoked, or the business is not active. |
| 404 | gift_card_not_found | The code doesn't exist on this business. |
| 409 | idempotency_key_conflict | The key was used on a DIFFERENT card. A reused key repeats only the exact call it was used for — it can never succeed on a new card. |
| 409 | cash_claim_cannot_be_denied | noCashClaim cannot be set on a SOLD card. A card the customer has paid for carries the right to have the remaining balance paid out in cash, and that right a flag cannot remove — issue as b2b or comp. |
| 404 | merchant_not_found | The key is valid, but the business behind it no longer exists. Rare, and not something a client can fix — contact us. |
| 404 | order_not_found | Resend found the card, but not the order it came from. A card issued by hand has no order and therefore cannot be resent that way. |
| 409 | card_has_no_delivery | The card was never sent by us — it was handed over the counter. There is no delivery to repeat. |
| 409 | order_has_recipient_list | The order is addressed card by card, and so there is not one address on it to fix. Resend the single card with recipient instead — it is the one holder the correction is about. |
| 422 | invalid_recipient | recipient in the body of resend is not an email address we can send to. Omit the field to send to the address the card already has. |
| 502 | delivery_failed | We reached our provider, and they rejected the delivery. The card has no fault, and nothing was charged — try again, or check the address. |
Redemption has its own responses beyond that — the card's state, validity, the delay and the balance. They stand together in the table under Redeem on the Gift Card page. One of them repeats: card_inactive answers Reverse a redemption with as well, but on a narrower gate — there it is only a cancelled or frozen card, and that has its own table further down.