Due to PCI compliant reasons we're going to turn off support for TLS v1.0 on all of our servers.
Please check/update you API implementations to support TLS v1.2 until 29.06.2018

REST API CodeDefinition

From XING Events Developer Documentation
Jump to: navigation, search

Object type: CodeDefinition

This page contains information about all properties and methods for the definition of promotion codes.
The codeDefinition object defines what actions are performed by the ticket shop if a code of this type is entered by the ticket buyer.
One codeDefinition may contain multiple or just one "code". A code is the string that the user can enter in the shop and may be valid multiple times or just once.

Properties

Attributes: R - accessible in read requests W - accessible in write (update) requests C - accessible in create requests

Property
Type
Attributes
Description
Required/Optional
id
Integer R--
The internal id of this object.
type CodeType R-C
Type of this code. Details required
name String R-C
Name of this promotion code definition. The name may contain the following symbols: a-z, A-Z, 0-9, hyphen, underscore/underline. required
value
Percent or Money R-C
If the code is of type DISCOUNTCODE_TYPE_PERCENT this will define the percentage of the ticket/payment price that will be deducted with this code.

If the code is of type DISCOUNTCODE_TYPE_ABSOLUTE this will define the amount of money that will be deducted with this code (the currency unit is the currency of the event).
If the code is of type DISCOUNTCODE_TYPE_CATEGORY this value will be ignored.

required
(for type: DISCOUNTCODE_TYPE_PERCENT, DISCOUNTCODE_TYPE_ABSOLUTE)
categories
Array of Integer R-C
If the code is of type DISCOUNTCODE_TYPE_CATEGORY this value contains an array of category IDs that this code will unlock if used.

If the code is of any other type the discount will only be applied to the specified categories.
If no category IDs are provided the code applies to all existing and not yet created categories of this event.

optional (Default: empty)
active
Boolean R-C
Is this code enable or disabled and therefore currently not usable by a ticket buyer.
optional (Default: true)
validCount Integer R-C
How often can each code of this type be used. If not provided the code can be used unlimited times.
optional (Default: empty)
startDate Date R-C
The date this code starts to be valid. If not provided the code can be used from now on.
optional (Default: empty)
endDate Date R-C
The date this code stops to be valid. If not provided the code can be used forever.
optional (Default: empty)

Methods

Enumerate Code Definitions

See Enumerate codeDefinitions in the event object.

Read

Call GET /api/codeDefinition/<id>
Description This request will return the codeDefinition object with the specified internal id. The response contains all properties marked with R.
Response {"codeDefinition":{"id": ...}, "success":true}.
Errors

See General Errorcodes.

Create

Call POST /api/event/<id>/codeDefinition/create
Parameters The parameters defined in the table above that are marked with "C"
count — How many codes should be generated with the creation of this code definition (default: 1).

If count equals 0 the system will note create any "code" within this code definition. Use the Add codes function to add codes to this codeDefinition.
If count equals 1 the system will create one "code" within this code definition that has the same "name" as this codeDefinition. That means a ticketBuyer can enter the name of this codeDefinion in the ticket shop to apply this code.
If count is greater 1 the system will use the codeDefinition name as a prefix appended by a random string to generate unique multiple codes the users can enter. The random string will not contain any special characters or any character of "OIB018" to prevent misunderstandings for the user while entering the code.

Description This request will create a new code definition and depending on the count property create codes for it.
Response {"id":..., "success":true}.
Errors com.amiando.ticketing.TicketShop.InvalidFormatException.name name exists or contains invalid characters

com.amiando.ticketing.TicketShop.InvalidFormatException.value the entered value is invalid (for this code type)
com.amiando.ticketing.TicketShop.InvalidFormatException.validCount the entered validCount is negative
See General Errorcodes.

Enumerate codes

Call GET /api/codeDefinition/<id>/codes
Parameters pageSize: Define the maximum number of codes you want to receive with this call (default and maximum value is 500).

page: If this codeDefinition has more codes as requested by the pageSize, use the page parameter to get the next page of codes. Example: "pageSize=100&page=0" will return the first 100 codes. "pageSize=100&page=1" will return the codes number 101 to 200.

Description This request will return all codes in this codeDefinition. The codes are those strings the user can enter in the ticket shop to get what is defined in this codeDefinition. Many codeDefinitions probably just contain one code, but as some users also need hundreds or thousands of codes, the codes are returned in a pageable matter, returning a maximum of 500 codes at once.
Response {"lastPage": ..., "totalResults":..., "currentPage":..., "success": true, "codes":[{"codeDefinitionId":..., "code": ..., "used": ..., "lastPaymentId": ...},...,{...}]}

As this call returns the codes in a pageable matter, the return value contains additional information about the pages:
lastPage: returns how many pages exist (zero based)
currentPage: the current page that is returned (zero based)
The codes array returns the codes of this codeDefinition:
codeDefinitionId: id of this codeDefinition
code: the code itself (the string the ticket buyer can enter in the ticket shop)
used: how many time was this code used by now
lastPaymentId: in case the code was used already, this parameter exists and will return the payment id of the last purchase that used this code.

Errors See General Errorcodes.

Add codes

Call POST /api/codeDefinition/<id>/add
Parameters codes (required): A coma separated list of codes you want to add to this codeDefinition.
Description With this call you can add codes to your codeDefinition (instead of (or additional to) the automatic code generation during the codeDefinition creation with the parameter count).

If for example you want to create codes matching your specific strings (e.g. your customer IDs) you can create a codeDefinion with "count=0" to create an "empty" codeDefinition and afterwards use this function to add all your customer IDs to the codeDefinion resulting in you clients to be able to enter their customer ID as a promotion code in the shop.

Response {"success":true}
Errors com.amiando.api.rest.MissingParam.codes

com.amiando.api.rest.DiscountCodeExistsException
See General Errorcodes.

Find code

Call GET /api/event/<id>/codeDefinition/findCode
Parameters code (required): The code string to be searched for.
Description Searches for the provided code in all codeDefinitions of the selected event. If the code was not found, the return value does not contain any code information and only returns { "success": true }
Response {"code": {"codeDefinitionId": ..., "code": ..., "used": ..., "lastPaymentId:" ...}, "success":true}.</br>

codeDefinitionId: id of the codeDefinition the found code belongs to
code: the code string (same that was provided as the parameter in this call)
used: how many time was this code used by now
lastPaymentId: in case the code was used already, this parameter exists and will return the payment id of the last purchase that used this code.

Errors com.amiando.api.rest.MissingParam.code

See General Errorcodes.

Code Type

The type property indicates what this code is used for. Possible values are:

Code Type
Description
DISCOUNTCODE_TYPE_PERCENT
Means that this code will give a discount to the ticket buyer to purchase tickets. The value property of the code will define the percentage that will be deducted from the of the ticket price.
DISCOUNTCODE_TYPE_ABSOLUTE
Means that this code will give a discount to the ticket buyer to purchase tickets. The value property of the code will define the amount of money that will be deducted (the currency unit is the currency of the event).
DISCOUNTCODE_TYPE_CATEGORY
Means that if this code is used by a ticket buyer a hidden category will be unlocked. Which categories will be unlocked is defined in the categories property.
DISCOUNTCODE_TYPE_REGISTRATION
deprecated
This code was used to unlock old registration form events that do not exist anymore on the platform.
REST API Contents
Getting Started Get your API key Overview Formats Errors
Data Types Event Participant Payment Ticket
Ticket Categories ProductDefinition Products CodeDefinition
TicketShop Addresses Ticket Types Payment Types
BankAccount UserDataDefinition UserData User
Partner ApiKey
Data Synchronization Sync Interface