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`)
owner_ticket	integer	Internal ID of an order position that is the “owner” of this gift card and can view all transactions. When setting this field, you can also give the `secret` of an order position.
issuer	string	Organizer slug of the organizer who created this gift card and is responsible for it.

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`)
info	object	Additional data about the transaction (or `null`)
acceptor	string	Organizer slug of the organizer who created this transaction (can be `null` for all transactions performed before this field was added.)

Changed in version 4.20: The owner_ticket and issuer attributes of the gift card and the info and acceptor attributes of the gift card transaction resource have been added.

Endpoints¶

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,
      "owner_ticket": null,
      "issuer": "bigevents",
      "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.
value (string) – Only show gift cards with the given value.
expired (boolean) – Filter for gift cards that are (not) expired.
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.
expand (string) – If you pass "owner_ticket", the respective field will be shown as a nested value instead of just an ID. The nested objects are identical to the respective resources, except that the owner_ticket will have an attribute of the format "order": {"code": "ABCDE", "event": "eventslug"} to make matching easier. The parameter can be given multiple times.

Parameters:

organizer – The slug field of the organizer to fetch

Status Codes:

200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer does not exist or you have no permission to view this resource.

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,
  "owner_ticket": null,
  "issuer": "bigevents",
  "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:

200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer does not exist or you have no permission to view this resource.

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,
  "owner_ticket": null,
  "issuer": "bigevents",
  "value": "13.37"
}

Parameters:

organizer – The slug field of the organizer to create a gift card for

Query Parameters:

expand (string) – If you pass "owner_ticket", the respective field will be shown as a nested value instead of just an ID. The nested objects are identical to the respective resources, except that the owner_ticket will have an attribute of the format "order": {"code": "ABCDE", "event": "eventslug"} to make matching easier. The parameter can be given multiple times.

Status Codes:

201 Created – no error
400 Bad Request – The gift card could not be created due to invalid submitted data.
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer does not exist or you have no permission to create this resource.

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,
  "owner_ticket": null,
  "issuer": "bigevents",
  "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,
  "owner_ticket": null,
  "issuer": "bigevents",
  "value": "15.37"
}

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,
      "acceptor": "bigevents",
      "info": {
        "created_by": "plugin1"
      }
    }
  ]
}

Parameters:

organizer – The slug field of the organizer to view
id – The id field of the gift card to view

Status Codes:

200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer does not exist or you have no permission to view this resource.