API reference

Gift cards

Issue, read and disable gift cards.

On this page

List gift cards
Issue a gift card
Get a gift card
Disable a gift card

List gift cards

get/gift-cards

Required scopes:read_gift_cards

Query parameters

Name	Type	Description
`limit`	integer	Page size, 1–250 (default 50). default 50 · min 1 · max 250
`cursor`	string	next_cursor from the previous page.
`updated_since`	string<date-time>	Only objects changed at or after this ISO-8601 time.
`created_since`	string<date-time>	Only objects created at or after this ISO-8601 time.
`status`	string	Status. One of:`activeusedexpireddisabled`
`customer_id`	integer	Of this customer.

Example request

curl

curl "https://api.sellorchard.com/v1/gift-cards?limit=50" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY"

Response200Gift cards.

Show response schema

dataarray of GiftCardrequired
ShowHide item attributes
- objectstringrequired
- idintegerrequired
  Id.
- codestring
  The full code: only in the response that issues the card.
- last4stringrequired
  Last four characters of the code.
- initial_valuestringrequired
  Value when issued.
  pattern ^-?\d+\.\d{2}$
- balancestringrequired
  Balance left.
  pattern ^-?\d+\.\d{2}$
- currencystringrequired
  Currency.
- statusstringrequired
  Right now.
  One of:activeusedexpireddisabled
- sourcestring | nullrequired
  How it was issued.
- customer_idinteger | nullrequired
  Customer.
- order_idinteger | nullrequired
  Order that bought it.
- recipient_emailstring | nullrequired
  Recipient.
- recipient_namestring | nullrequired
  Recipient name.
- notestring | nullrequired
  Staff note.
- expires_atstring<date-time> | nullrequired
  Expiry.
- disabled_atstring<date-time> | nullrequired
  Disabled.
- created_atstring<date-time>required
  Issued.
- updated_atstring<date-time>required
  Last changed.
has_morebooleanrequired
More pages after this one.
next_cursorstring | nullrequired
Pass as cursor for the next page; null on the last page.

200 response

{
  "data": [
    {
      "object": "gift_card",
      "id": 77,
      "last4": "Q7K2",
      "initial_value": "50.00",
      "balance": "50.00",
      "currency": "USD",
      "status": "active",
      "source": "api",
      "customer_id": null,
      "order_id": null,
      "recipient_email": "sam@example.com",
      "recipient_name": "Sam",
      "note": null,
      "expires_at": null,
      "disabled_at": null,
      "created_at": "2026-11-02T15:00:00Z",
      "updated_at": "2026-11-02T15:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Error responses

400invalid_requestMalformed request (e.g. a bad cursor).
401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
422invalid_requestInvalid parameters; errors lists each field.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Issue a gift card

post/gift-cards

The full code is in this response only. Fires gift_card.issued.

Required scopes:write_gift_cards

Headers

Name	Type	Description
`Idempotency-Key`	string	Any unique string (e.g. a UUID, up to 255 characters). A retry with the same key and body within 24 hours gets the first response again (Idempotent-Replayed: true); the same key with a different body is a 409 conflict.

Request body

valuestring | numberrequired
Value (0.01–100000).
codestring | null
Your own code (8–32 letters and numbers); generated when empty.
expires_atstring<date> | null
Expiry date (after today).
customer_idinteger | null
Customer.
recipient_emailstring<email> | null
Recipient.
recipient_namestring | null
Recipient name.
messagestring | null
Message in the email.
notestring | null
Staff note.
send_emailboolean
Email the card to the recipient now.

Example request

curl

curl -X POST "https://api.sellorchard.com/v1/gift-cards" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "50.00"
}'

Response201The card, with its full code (shown only here).

Show response schema

dataGiftCardrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Id.
- codestring
  The full code: only in the response that issues the card.
- last4stringrequired
  Last four characters of the code.
- initial_valuestringrequired
  Value when issued.
  pattern ^-?\d+\.\d{2}$
- balancestringrequired
  Balance left.
  pattern ^-?\d+\.\d{2}$
- currencystringrequired
  Currency.
- statusstringrequired
  Right now.
  One of:activeusedexpireddisabled
- sourcestring | nullrequired
  How it was issued.
- customer_idinteger | nullrequired
  Customer.
- order_idinteger | nullrequired
  Order that bought it.
- recipient_emailstring | nullrequired
  Recipient.
- recipient_namestring | nullrequired
  Recipient name.
- notestring | nullrequired
  Staff note.
- expires_atstring<date-time> | nullrequired
  Expiry.
- disabled_atstring<date-time> | nullrequired
  Disabled.
- created_atstring<date-time>required
  Issued.
- updated_atstring<date-time>required
  Last changed.

201 response

{
  "data": {
    "object": "gift_card",
    "id": 77,
    "code": "AB3D-9F2K-7LMN-Q7K2",
    "last4": "Q7K2",
    "initial_value": "50.00",
    "balance": "50.00",
    "currency": "USD",
    "status": "active",
    "source": "api",
    "customer_id": null,
    "order_id": null,
    "recipient_email": "sam@example.com",
    "recipient_name": "Sam",
    "note": null,
    "expires_at": null,
    "disabled_at": null,
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-02T15:00:00Z"
  }
}

Error responses

401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
409conflictThe Idempotency-Key was used with a different request, or that request is still running.
422invalid_requestInvalid parameters; errors lists each field.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Get a gift card

get/gift-cards/{id}

Required scopes:read_gift_cards

Path parameters

Name	Type	Description
`id`required	integer	The object id.

Example request

curl

curl "https://api.sellorchard.com/v1/gift-cards/120" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY"

Response200A gift card.

Show response schema

dataGiftCardrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Id.
- codestring
  The full code: only in the response that issues the card.
- last4stringrequired
  Last four characters of the code.
- initial_valuestringrequired
  Value when issued.
  pattern ^-?\d+\.\d{2}$
- balancestringrequired
  Balance left.
  pattern ^-?\d+\.\d{2}$
- currencystringrequired
  Currency.
- statusstringrequired
  Right now.
  One of:activeusedexpireddisabled
- sourcestring | nullrequired
  How it was issued.
- customer_idinteger | nullrequired
  Customer.
- order_idinteger | nullrequired
  Order that bought it.
- recipient_emailstring | nullrequired
  Recipient.
- recipient_namestring | nullrequired
  Recipient name.
- notestring | nullrequired
  Staff note.
- expires_atstring<date-time> | nullrequired
  Expiry.
- disabled_atstring<date-time> | nullrequired
  Disabled.
- created_atstring<date-time>required
  Issued.
- updated_atstring<date-time>required
  Last changed.

200 response

{
  "data": {
    "object": "gift_card",
    "id": 77,
    "last4": "Q7K2",
    "initial_value": "50.00",
    "balance": "50.00",
    "currency": "USD",
    "status": "active",
    "source": "api",
    "customer_id": null,
    "order_id": null,
    "recipient_email": "sam@example.com",
    "recipient_name": "Sam",
    "note": null,
    "expires_at": null,
    "disabled_at": null,
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-02T15:00:00Z"
  }
}

Error responses

401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
404not_foundNo such object in this store.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Disable a gift card

post/gift-cards/{id}/disable

Required scopes:write_gift_cards

Path parameters

Name	Type	Description
`id`required	integer	The object id.

Headers

Name	Type	Description
`Idempotency-Key`	string	Any unique string (e.g. a UUID, up to 255 characters). A retry with the same key and body within 24 hours gets the first response again (Idempotent-Replayed: true); the same key with a different body is a 409 conflict.

Example request

curl

curl -X POST "https://api.sellorchard.com/v1/gift-cards/120/disable" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Response200A gift card.

Show response schema

dataGiftCardrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Id.
- codestring
  The full code: only in the response that issues the card.
- last4stringrequired
  Last four characters of the code.
- initial_valuestringrequired
  Value when issued.
  pattern ^-?\d+\.\d{2}$
- balancestringrequired
  Balance left.
  pattern ^-?\d+\.\d{2}$
- currencystringrequired
  Currency.
- statusstringrequired
  Right now.
  One of:activeusedexpireddisabled
- sourcestring | nullrequired
  How it was issued.
- customer_idinteger | nullrequired
  Customer.
- order_idinteger | nullrequired
  Order that bought it.
- recipient_emailstring | nullrequired
  Recipient.
- recipient_namestring | nullrequired
  Recipient name.
- notestring | nullrequired
  Staff note.
- expires_atstring<date-time> | nullrequired
  Expiry.
- disabled_atstring<date-time> | nullrequired
  Disabled.
- created_atstring<date-time>required
  Issued.
- updated_atstring<date-time>required
  Last changed.

200 response

{
  "data": {
    "object": "gift_card",
    "id": 77,
    "last4": "Q7K2",
    "initial_value": "50.00",
    "balance": "50.00",
    "currency": "USD",
    "status": "active",
    "source": "api",
    "customer_id": null,
    "order_id": null,
    "recipient_email": "sam@example.com",
    "recipient_name": "Sam",
    "note": null,
    "expires_at": null,
    "disabled_at": null,
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-02T15:00:00Z"
  }
}

Error responses

401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
404not_foundNo such object in this store.
409conflictThe Idempotency-Key was used with a different request, or that request is still running.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.