Gift cards

Resource description

The gift card resource contains the following public fields:

Field

Type

Description

id

integer

Internal ID of the gift card

secret

string

Gift card code (can not be modified later)

value

money (string)

Current gift card value

currency

string

Currency of the value (can not be modified later)

testmode

boolean

Whether this is a test gift card

expires

datetime

Expiry date (or null)

conditions

string

Special terms and conditions for this card (or null)

The gift card transaction resource contains the following public fields:

Field

Type

Description

id

integer

Internal ID of the gift card transaction

datetime

datetime

Creation date of the transaction

value

money (string)

Transaction amount

event

string

Event slug, if the gift card was used in the web shop (or null)

order

string

Order code, if the gift card was used in the web shop (or null)

text

string

Custom text of the transaction (or null)

Endpoints

New in version 3.14: The transaction list endpoint was added.

GET /api/v1/organizers/(organizer)/giftcards/

Returns a list of all gift cards issued by a given organizer.

Example request:

GET /api/v1/organizers/bigevents/giftcards/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "secret": "HLBYVELFRC77NCQY",
      "currency": "EUR",
      "testmode": false,
      "expires": null,
      "conditions": null,
      "value": "13.37"
    }
  ]
}
Query Parameters
  • page (integer) – The page number in case of a multi-page result set, default is 1

  • secret (string) – Only show gift cards with the given secret.

  • testmode (boolean) – Filter for gift cards that are (not) in test mode.

  • include_accepted (boolean) – Also show gift cards issued by other organizers that are accepted by this organizer.

Parameters
  • organizer – The slug field of the organizer to fetch

Status Codes
GET /api/v1/organizers/(organizer)/giftcards/(id)/

Returns information on one gift card, identified by its ID.

Example request:

GET /api/v1/organizers/bigevents/giftcards/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "id": 1,
  "secret": "HLBYVELFRC77NCQY",
  "currency": "EUR",
  "testmode": false,
  "expires": null,
  "conditions": null,
  "value": "13.37"
}
Parameters
  • organizer – The slug field of the organizer to fetch

  • id – The id field of the gift card to fetch

Query Parameters
  • include_accepted (boolean) – Also show gift cards issued by other organizers that are accepted by this organizer.

Status Codes
POST /api/v1/organizers/(organizer)/giftcards/

Creates a new gift card

Example request:

POST /api/v1/organizers/bigevents/giftcards/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json

{
  "secret": "HLBYVELFRC77NCQY",
  "currency": "EUR",
  "value": "13.37"
}

Example response:

HTTP/1.1 201 Created
Vary: Accept
Content-Type: application/json

{
  "id": 1,
  "secret": "HLBYVELFRC77NCQY",
  "testmode": false,
  "currency": "EUR",
  "expires": null,
  "conditions": null,
  "value": "13.37"
}
Parameters
  • organizer – The slug field of the organizer to create a gift card for

Status Codes
PATCH /api/v1/organizers/(organizer)/giftcards/(id)/

Update a gift card. You can also use PUT instead of PATCH. With PUT, you have to provide all fields of the resource, other fields will be reset to default. With PATCH, you only need to provide the fields that you want to change.

You can change all fields of the resource except the id, secret, testmode, and currency fields. Be careful when modifying the value field to avoid race conditions. We recommend to use the transact method described below.

Example request:

PATCH /api/v1/organizers/bigevents/giftcards/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json
Content-Length: 94

{
  "value": "14.00"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "id": 1,
  "secret": "HLBYVELFRC77NCQY",
  "testmode": false,
  "currency": "EUR",
  "expires": null,
  "conditions": null,
  "value": "14.00"
}
Parameters
  • organizer – The slug field of the organizer to modify

  • id – The id field of the gift card to modify

Status Codes
  • 200 OK – no error

  • 400 Bad Request – The gift card could not be modified due to invalid submitted data

  • 401 Unauthorized – Authentication failure

  • 403 Forbidden – The requested organizer does not exist or you have no permission to change this resource.

POST /api/v1/organizers/(organizer)/giftcards/(id)/transact/

Atomically change the value of a gift card. A positive amount will increase the value of the gift card, a negative amount will decrease it.

Example request:

POST /api/v1/organizers/bigevents/giftcards/1/transact/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json
Content-Length: 79

{
  "value": "2.00",
  "text": "Optional value explaining the transaction"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "id": 1,
  "secret": "HLBYVELFRC77NCQY",
  "currency": "EUR",
  "testmode": false,
  "expires": null,
  "conditions": null,
  "value": "15.37"
}

Changed in version 3.5: This endpoint now returns status code 409 if the transaction would lead to a negative gift card value.

Parameters
  • organizer – The slug field of the organizer to modify

  • id – The id field of the gift card to modify

Query Parameters
  • include_accepted (boolean) – Also show gift cards issued by other organizers that are accepted by this organizer.

Status Codes
  • 200 OK – no error

  • 400 Bad Request – The gift card could not be modified due to invalid submitted data

  • 401 Unauthorized – Authentication failure

  • 403 Forbidden – The requested organizer does not exist or you have no permission to change this resource.

  • 409 Conflict – There is not sufficient credit on the gift card.

GET /api/v1/organizers/(organizer)/giftcards/(id)/transactions/

List all transactions of a gift card.

Example request:

GET /api/v1/organizers/bigevents/giftcards/1/transactions/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 82,
      "datetime": "2020-06-22T15:41:42.800534Z",
      "value": "50.00",
      "event": "democon",
      "order": "FXQYW",
      "text": null
    }
  ]
}
Parameters
  • organizer – The slug field of the organizer to view

  • id – The id field of the gift card to view

Status Codes