{ "openapi": "3.0.0", "servers": [ { "url": "https://vouchers.api.jtl-software.com/v1", "description": "JTL-Voucher Cloud API (Production)" }, { "url": "https://vouchers-sbx.api.jtl-software.com/v1", "description": "JTL-Voucher Cloud API (Sandbox)" } ], "info": { "version": "1.8", "title": "JTL-Voucher Cloud API", "description": "# Introduction\nWelcome to the JTL Voucher Cloud API documentation.\nHere you will find all information to get started using our API in your projects.", "contact": { "name": "JTL-Software-GmbH", "url": "https://www.jtl-software.com", "email": "info@jtl-software.de" } }, "tags": [ { "name": "Vouchers" }, { "name": "Reservations" }, { "name": "Charges" }, { "name": "Clients" } ], "x-tagGroups": [ { "name": "API calls", "tags": [ "Vouchers", "Reservations", "Charges", "Clients" ] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "oauth2", "description": "This API uses OAuth 2 with Client Credentials Flow (see: https://www.oauth.com/oauth2-servers/access-tokens/client-credentials).\n\n> You can request only a subset of specific scopes for your client, however the available scopes for each client are defined through the client groups in the UI.\n\n> Within your token request, you can also send the optional parameter *client_type* (string with a max length of 32 chars). This value is only used for internal statistics.\n", "flows": { "clientCredentials": { "tokenUrl": "https://vouchers.api.jtl-software.com/oauth/token", "scopes": { "read": "Read single vouchers", "read-lists": "Read voucher lists", "read-secrets": "Read secret voucher information like code and pin", "use": "Use a voucher (activation, reservation, charge and cancel)", "manage": "Create and delete vouchers", "update": "Update vouchers", "recharge": "Recharge a voucher" } } } } } }, "security": [ { "BearerAuth": [ "read", "read-lists", "read-secrets", "use", "manage", "update", "recharge" ] } ], "paths": { "/vouchers": { "get": { "tags": [ "Vouchers" ], "summary": "Get a list of vouchers", "description": "This call will give you a paginated list of vouchers.", "security": [ { "BearerAuth": [ "read-lists" ] } ], "parameters": [ { "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 2 }, { "in": "query", "name": "per_page", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 25 }, "example": 10 }, { "in": "query", "name": "filter[created_from]", "required": false, "schema": { "type": "string", "format": "RFC3339" }, "example": "2017-07-21T17:32:28+00:00", "description": "Sets a filter to get all entries from this datetime - must be set in RFC3339 format, see https://tools.ietf.org/html/rfc3339" }, { "in": "query", "name": "filter[created_to]", "required": false, "schema": { "type": "string", "format": "RFC3339" }, "example": "2017-07-21T17:32:28Z+00:00", "description": "Sets a filter to get all entries up to this datetime - must be set in RFC3339 format, see https://tools.ietf.org/html/rfc3339" }, { "in": "query", "name": "filter[valid_until_from]", "required": false, "schema": { "type": "string", "format": "RFC3339" }, "example": "2017-07-21T17:32:28Z", "description": "Sets a filter to get all entries from this datetime - must be set in RFC3339 format, see https://tools.ietf.org/html/rfc3339" }, { "in": "query", "name": "filter[valid_until_to]", "required": false, "schema": { "type": "string", "format": "RFC3339" }, "example": "2017-07-21T17:32:28Z", "description": "Sets a filter to get all entries up to this datetime - must be set in RFC3339 format, see https://tools.ietf.org/html/rfc3339" }, { "in": "query", "name": "filter[client_id]", "required": false, "schema": { "type": "string" }, "style": "form", "example": "cff8784e5eb28b81ca02a", "description": "Sets a filter to get all entries of this client" }, { "in": "query", "name": "filter[client.client_group_id]", "required": false, "schema": { "type": "string" }, "style": "form", "example": "da39a3ee5eb28b7392ef5", "description": "Sets a filter to get all entries of this group" }, { "in": "query", "name": "filter[code]", "required": false, "schema": { "type": "string" }, "style": "form", "example": "1A8S-9YSY-6EOB-KVNW", "description": "Sets a filter to get a voucher with this specific code" }, { "in": "query", "name": "filter[id]", "required": false, "schema": { "type": "string" }, "style": "form", "example": "A37FX", "description": "Sets a filter to get all entries having this voucher id" }, { "in": "query", "name": "filter[sku]", "required": false, "schema": { "type": "string" }, "style": "form", "example": "JHG75HJG", "description": "Sets a filter to get all entries having this SKU" }, { "in": "query", "name": "filter[type]", "required": false, "schema": { "type": "string", "enum": [ "digital", "print" ] }, "style": "form", "example": "digital", "description": "Sets a filter to get only entries of this type" }, { "in": "query", "name": "filter[amount]", "required": false, "schema": { "type": "string" }, "style": "form", "example": "10.53", "description": "Sets a filter to get all entries having this amount" }, { "in": "query", "name": "filter[status]", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "example": [ "inactive", "active" ], "description": "Sets a filter to get all entries with this status" }, { "in": "query", "name": "filter[batch]", "required": false, "schema": { "type": "string" }, "style": "form", "example": "123", "description": "Sets a filter to get all entries that belongs to a specific batch" }, { "in": "query", "name": "filter[remaining_amount]", "required": false, "schema": { "type": "boolean" }, "style": "form", "example": true, "description": "Set to true to get only vouchers that still have credit. Set to false to get vouchers without remaining credit." }, { "in": "query", "name": "filter[taxable]", "required": false, "schema": { "type": "boolean" }, "style": "form", "example": false, "description": "Sets a filter to get only vouchers that are taxable or not" }, { "in": "query", "name": "filter[tax_rate]", "required": false, "schema": { "type": "string" }, "style": "form", "example": "19", "description": "Sets a filter to get only vouchers with this tax rate" }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at" ] } }, "style": "form", "example": [ "created_at" ], "description": "Sets one or multiple fields to sort the result. Each field can be prefixed by a minus sign (-) to sort descending." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "A unique custom identifier for this voucher (e.g. a sku). Also used for activation of this voucher. (optional, if not set for this voucher it will be auto generated based on the UI regex settings)", "maxLength": 255, "example": "4ZH83T0ACUUC14CW" }, "client_id": { "type": "string", "description": "id of the client that created this voucher", "readOnly": true, "example": "da39a3ee5eb28b7392ef5" }, "sku": { "type": "string", "maxLength": 255, "description": "Optional SKU", "example": "AJHS8675FG" }, "batch": { "type": "string", "maxLength": 30, "description": "Optional campaign or grouping identifier", "example": "Winter Campaign" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "currency": { "type": "string", "description": "The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "minLength": 3, "maxLength": 3, "example": "EUR" }, "valid_until": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "Date until which this voucher is valid and can be redeemed. Calculated based on validity_value and validity_interval on activation. This property will be null if the voucher is inactive.", "example": "2025-07-21T17:32:28+00:00" }, "validity_value": { "type": "integer", "description": "Calculates together with validity_interval the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": 24 }, "validity_interval": { "type": "string", "enum": [ "days", "weeks", "months", "years" ], "description": "Calculates together with validity_value the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": "months" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "The status of this voucher. In general vouchers are inactive when created, and gets activated when payed. Only activated vouchers can be charged.", "example": "active" }, "type": { "type": "string", "enum": [ "print", "digital" ], "description": "Defines if this voucher is printed or digital. Printed vouchers will have the status inactive by default.", "example": "digital" }, "taxable": { "type": "boolean", "description": "Defines if this voucher is a taxable multi purpose voucher", "example": true, "default": false }, "tax_rate": { "type": "string", "description": "The tax rate for this voucher (only required when taxable is true)", "example": "19" }, "order_number": { "type": "string", "description": "An optional order number for this voucher", "example": "Order 66" }, "data": { "type": "string", "description": "Any additional custom data for this voucher as a JSON string", "example": "{\"foo\": \"bar\"}" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } }, { "properties": { "remaining_amount": { "type": "string", "example": "5.50", "description": "The remaining amount of this voucher" }, "deletable": { "type": "boolean", "example": true, "description": "Indicates if this voucher is deletable as it was not used yet" } } } ] } } } }, { "type": "object", "properties": { "links": { "type": "object", "properties": { "first": { "type": "string", "maxLength": 255, "description": "First page link", "example": "http://domain/v1/vouchers?page=1" }, "last": { "type": "string", "maxLength": 255, "description": "Last page link", "example": "http://domain/v1/vouchers?page=5" }, "prev": { "type": "string", "nullable": true, "maxLength": 255, "description": "Previous page link", "example": "http://domain/v1/vouchers?page=3" }, "next": { "type": "string", "nullable": true, "maxLength": 255, "description": "Next page link", "example": "http://domain/v1/vouchers?page=2" } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1, "description": "Current page", "example": 1 }, "per_page": { "type": "integer", "minimum": 1, "description": "Limit per page", "example": 15 }, "from": { "type": "integer", "minimum": 1, "nullable": true, "description": "Start of pagination", "example": 1 }, "to": { "type": "integer", "minimum": 1, "nullable": true, "description": "Start of pagination", "example": 15 }, "last_page": { "type": "integer", "minimum": 1, "description": "Last page", "example": 167 }, "total": { "type": "integer", "minimum": 1, "description": "Total pages count", "example": 2500 }, "path": { "type": "string", "maxLength": 255, "description": "Current path link", "example": "http://domain/v1/vouchers" } } } } } ] } } } } } }, "post": { "tags": [ "Vouchers" ], "summary": "Create a new voucher", "description": "Use this call to create a new voucher", "security": [ { "BearerAuth": [ "manage" ] } ], "operationId": "create", "requestBody": { "description": "Voucher create request body", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "A unique custom identifier for this voucher (e.g. a sku). Also used for activation of this voucher. (optional, if not set for this voucher it will be auto generated based on the UI regex settings)", "maxLength": 255, "example": "4ZH83T0ACUUC14CW" }, "client_id": { "type": "string", "description": "id of the client that created this voucher", "readOnly": true, "example": "da39a3ee5eb28b7392ef5" }, "sku": { "type": "string", "maxLength": 255, "description": "Optional SKU", "example": "AJHS8675FG" }, "batch": { "type": "string", "maxLength": 30, "description": "Optional campaign or grouping identifier", "example": "Winter Campaign" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "currency": { "type": "string", "description": "The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "minLength": 3, "maxLength": 3, "example": "EUR" }, "valid_until": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "Date until which this voucher is valid and can be redeemed. Calculated based on validity_value and validity_interval on activation. This property will be null if the voucher is inactive.", "example": "2025-07-21T17:32:28+00:00" }, "validity_value": { "type": "integer", "description": "Calculates together with validity_interval the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": 24 }, "validity_interval": { "type": "string", "enum": [ "days", "weeks", "months", "years" ], "description": "Calculates together with validity_value the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": "months" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "The status of this voucher. In general vouchers are inactive when created, and gets activated when payed. Only activated vouchers can be charged.", "example": "active" }, "type": { "type": "string", "enum": [ "print", "digital" ], "description": "Defines if this voucher is printed or digital. Printed vouchers will have the status inactive by default.", "example": "digital" }, "taxable": { "type": "boolean", "description": "Defines if this voucher is a taxable multi purpose voucher", "example": true, "default": false }, "tax_rate": { "type": "string", "description": "The tax rate for this voucher (only required when taxable is true)", "example": "19" }, "order_number": { "type": "string", "description": "An optional order number for this voucher", "example": "Order 66" }, "data": { "type": "string", "description": "Any additional custom data for this voucher as a JSON string", "example": "{\"foo\": \"bar\"}" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } }, { "properties": { "code": { "type": "string", "maxLength": 255, "description": "A code that must be entered during the ordering process to receive the savings indidcated on the assiciated voucher. (optional, if not set a code for this voucher will be auto generated based on the UI regex settings)", "example": "test" }, "pin": { "type": "string", "maxLength": 255, "description": "An additional security feature (covered) on printed vouchers, due to the fact that the code itself must be visible on the outside for activation of the voucher.", "example": "test" } } } ] } ], "required": [ "amount", "currency" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "A unique custom identifier for this voucher (e.g. a sku). Also used for activation of this voucher. (optional, if not set for this voucher it will be auto generated based on the UI regex settings)", "maxLength": 255, "example": "4ZH83T0ACUUC14CW" }, "client_id": { "type": "string", "description": "id of the client that created this voucher", "readOnly": true, "example": "da39a3ee5eb28b7392ef5" }, "sku": { "type": "string", "maxLength": 255, "description": "Optional SKU", "example": "AJHS8675FG" }, "batch": { "type": "string", "maxLength": 30, "description": "Optional campaign or grouping identifier", "example": "Winter Campaign" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "currency": { "type": "string", "description": "The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "minLength": 3, "maxLength": 3, "example": "EUR" }, "valid_until": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "Date until which this voucher is valid and can be redeemed. Calculated based on validity_value and validity_interval on activation. This property will be null if the voucher is inactive.", "example": "2025-07-21T17:32:28+00:00" }, "validity_value": { "type": "integer", "description": "Calculates together with validity_interval the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": 24 }, "validity_interval": { "type": "string", "enum": [ "days", "weeks", "months", "years" ], "description": "Calculates together with validity_value the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": "months" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "The status of this voucher. In general vouchers are inactive when created, and gets activated when payed. Only activated vouchers can be charged.", "example": "active" }, "type": { "type": "string", "enum": [ "print", "digital" ], "description": "Defines if this voucher is printed or digital. Printed vouchers will have the status inactive by default.", "example": "digital" }, "taxable": { "type": "boolean", "description": "Defines if this voucher is a taxable multi purpose voucher", "example": true, "default": false }, "tax_rate": { "type": "string", "description": "The tax rate for this voucher (only required when taxable is true)", "example": "19" }, "order_number": { "type": "string", "description": "An optional order number for this voucher", "example": "Order 66" }, "data": { "type": "string", "description": "Any additional custom data for this voucher as a JSON string", "example": "{\"foo\": \"bar\"}" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } }, { "properties": { "code": { "type": "string", "maxLength": 255, "description": "A code that must be entered during the ordering process to receive the savings indidcated on the assiciated voucher. (optional, if not set a code for this voucher will be auto generated based on the UI regex settings)", "example": "test" }, "pin": { "type": "string", "maxLength": 255, "description": "An additional security feature (covered) on printed vouchers, due to the fact that the code itself must be visible on the outside for activation of the voucher.", "example": "test" } } } ] } } } }, "422": { "description": "The request was well-formed but was unable to be followed due to semantic errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 422 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.CREATE.UNPROCESSABLE_ENTITY" }, "message": { "type": "string", "description": "The error message", "default": "The given data was invalid." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A unique code for this specific validation error", "example": "VOUCHER.CREATE.CURRENCY.VALID_CURRENCY" }, "property": { "type": "string", "description": "The property where the validation fails", "example": "currency" }, "rule": { "type": "string", "description": "The rule that caused the validation fail", "example": "valid_currency" }, "message": { "type": "string", "description": "The validation rule error message", "example": "Currency must be a valid currency code" } } } } } } } } } } } }, "/vouchers/recharge": { "post": { "tags": [ "Vouchers" ], "summary": "Recharge a voucher", "description": "Use this call to recharge a voucher. This can be used for example for customer cards. Please note that this call is not used for cancelations of previously charges.", "security": [ { "BearerAuth": [ "recharge" ] } ], "requestBody": { "description": "Voucher recharge request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 255, "description": "The vouchers code you want to recharge (not necessary if **id** is set)", "example": "test" }, "id": { "type": "string", "description": "The vouchers id you want to recharge (not necessary if **code** is set)", "maxLength": 255, "example": "4ZH83T0ACUUC14CW" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "currency": { "type": "string", "description": "The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes (must match the currency of the voucher)", "minLength": 3, "maxLength": 3, "example": "EUR" }, "order_number": { "type": "string", "description": "Order or invoice number of the transaction for this recharge", "example": "ORDER-62642" } }, "required": [ "amount", "currency", "order_number" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identification key - will be used in voucher-charge calls", "readOnly": true, "example": "cff8784e5eb28b9b04860" }, "voucher_id": { "type": "string", "description": "Voucher primary identification key (see voucher -> id)", "readOnly": true, "example": "cff8784e34b28b9b04860" }, "client_id": { "type": "string", "description": "Client primary identification key (see client -> id)", "readOnly": true, "example": "cff8784e5eb28b81ca02a" }, "type": { "type": "string", "enum": [ "charge", "recharge", "refund" ], "description": "Type of this charge. Can either be \"charge\", \"recharge\" or \"refund\"", "readOnly": true, "example": "charge" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "order_number": { "type": "string", "description": "Order or invoice number of the transaction", "example": "ORDER-62642" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } }, { "properties": { "type": { "example": "recharge" } } } ] } } } }, "403": { "description": "The request contained valid data and was understood by the server, but the server is refusing action.", "content": { "application/json": { "schema": { "type": "string", "example": "Forbidden" } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } }, "422": { "description": "The request was well-formed but was unable to be followed due to semantic errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 422 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.CREATE.UNPROCESSABLE_ENTITY" }, "message": { "type": "string", "description": "The error message", "default": "The given data was invalid." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A unique code for this specific validation error", "example": "VOUCHER.CREATE.CURRENCY.VALID_CURRENCY" }, "property": { "type": "string", "description": "The property where the validation fails", "example": "currency" }, "rule": { "type": "string", "description": "The rule that caused the validation fail", "example": "valid_currency" }, "message": { "type": "string", "description": "The validation rule error message", "example": "Currency must be a valid currency code" } } } } } } } } } } } }, "/vouchers/{id}": { "get": { "tags": [ "Vouchers" ], "summary": "Get a voucher", "description": "Use this call to get a specific single voucher. Please note that you wont get the vouchers secret properties *code* and *pin* (use the vouchers/{id}/complete call instead).", "security": [ { "BearerAuth": [ "read" ] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "da39a3ee3458b7392ef5" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "A unique custom identifier for this voucher (e.g. a sku). Also used for activation of this voucher. (optional, if not set for this voucher it will be auto generated based on the UI regex settings)", "maxLength": 255, "example": "4ZH83T0ACUUC14CW" }, "client_id": { "type": "string", "description": "id of the client that created this voucher", "readOnly": true, "example": "da39a3ee5eb28b7392ef5" }, "sku": { "type": "string", "maxLength": 255, "description": "Optional SKU", "example": "AJHS8675FG" }, "batch": { "type": "string", "maxLength": 30, "description": "Optional campaign or grouping identifier", "example": "Winter Campaign" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "currency": { "type": "string", "description": "The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "minLength": 3, "maxLength": 3, "example": "EUR" }, "valid_until": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "Date until which this voucher is valid and can be redeemed. Calculated based on validity_value and validity_interval on activation. This property will be null if the voucher is inactive.", "example": "2025-07-21T17:32:28+00:00" }, "validity_value": { "type": "integer", "description": "Calculates together with validity_interval the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": 24 }, "validity_interval": { "type": "string", "enum": [ "days", "weeks", "months", "years" ], "description": "Calculates together with validity_value the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": "months" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "The status of this voucher. In general vouchers are inactive when created, and gets activated when payed. Only activated vouchers can be charged.", "example": "active" }, "type": { "type": "string", "enum": [ "print", "digital" ], "description": "Defines if this voucher is printed or digital. Printed vouchers will have the status inactive by default.", "example": "digital" }, "taxable": { "type": "boolean", "description": "Defines if this voucher is a taxable multi purpose voucher", "example": true, "default": false }, "tax_rate": { "type": "string", "description": "The tax rate for this voucher (only required when taxable is true)", "example": "19" }, "order_number": { "type": "string", "description": "An optional order number for this voucher", "example": "Order 66" }, "data": { "type": "string", "description": "Any additional custom data for this voucher as a JSON string", "example": "{\"foo\": \"bar\"}" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } }, { "properties": { "remaining_amount": { "type": "string", "example": "5.50", "description": "The remaining amount of this voucher" }, "deletable": { "type": "boolean", "example": true, "description": "Indicates if this voucher is deletable as it was not used yet" } } } ] } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } } } }, "patch": { "tags": [ "Vouchers" ], "summary": "Update a voucher", "description": "Due to security restrictions only the sku and batch property can be updated on inactive vouchers", "security": [ { "BearerAuth": [ "update" ] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "da39a3ee3458b7392ef5" } ], "requestBody": { "description": "Voucher update request body", "required": true, "content": { "application/json": { "schema": { "properties": { "sku": { "type": "string", "maxLength": 255, "description": "Optional SKU", "example": "AJHS8675FG" }, "batch": { "type": "string", "maxLength": 30, "description": "Optional campaign or grouping identifier", "example": "Winter Campaign" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique custom identifier for this voucher (e.g. a sku). Also used for activation of this voucher. (optional, if not set for this voucher it will be auto generated based on the UI regex settings)", "maxLength": 255, "example": "4ZH83T0ACUUC14CW" }, "client_id": { "type": "string", "description": "id of the client that created this voucher", "readOnly": true, "example": "da39a3ee5eb28b7392ef5" }, "sku": { "type": "string", "maxLength": 255, "description": "Optional SKU", "example": "AJHS8675FG" }, "batch": { "type": "string", "maxLength": 30, "description": "Optional campaign or grouping identifier", "example": "Winter Campaign" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "currency": { "type": "string", "description": "The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "minLength": 3, "maxLength": 3, "example": "EUR" }, "valid_until": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "Date until which this voucher is valid and can be redeemed. Calculated based on validity_value and validity_interval on activation. This property will be null if the voucher is inactive.", "example": "2025-07-21T17:32:28+00:00" }, "validity_value": { "type": "integer", "description": "Calculates together with validity_interval the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": 24 }, "validity_interval": { "type": "string", "enum": [ "days", "weeks", "months", "years" ], "description": "Calculates together with validity_value the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": "months" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "The status of this voucher. In general vouchers are inactive when created, and gets activated when payed. Only activated vouchers can be charged.", "example": "active" }, "type": { "type": "string", "enum": [ "print", "digital" ], "description": "Defines if this voucher is printed or digital. Printed vouchers will have the status inactive by default.", "example": "digital" }, "taxable": { "type": "boolean", "description": "Defines if this voucher is a taxable multi purpose voucher", "example": true, "default": false }, "tax_rate": { "type": "string", "description": "The tax rate for this voucher (only required when taxable is true)", "example": "19" }, "order_number": { "type": "string", "description": "An optional order number for this voucher", "example": "Order 66" }, "data": { "type": "string", "description": "Any additional custom data for this voucher as a JSON string", "example": "{\"foo\": \"bar\"}" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } } } } }, "403": { "description": "The request contained valid data and was understood by the server, but the server is refusing action.", "content": { "application/json": { "schema": { "type": "string", "example": "Forbidden" } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } }, "422": { "description": "The request was well-formed but was unable to be followed due to semantic errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 422 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.CREATE.UNPROCESSABLE_ENTITY" }, "message": { "type": "string", "description": "The error message", "default": "The given data was invalid." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A unique code for this specific validation error", "example": "VOUCHER.CREATE.CURRENCY.VALID_CURRENCY" }, "property": { "type": "string", "description": "The property where the validation fails", "example": "currency" }, "rule": { "type": "string", "description": "The rule that caused the validation fail", "example": "valid_currency" }, "message": { "type": "string", "description": "The validation rule error message", "example": "Currency must be a valid currency code" } } } } } } } } } } }, "delete": { "tags": [ "Vouchers" ], "summary": "Delete a voucher", "description": "A voucher can only be deleted when it has no charges yet.", "security": [ { "BearerAuth": [ "manage" ] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "da39a3ee3458b7392ef5" } ], "requestBody": { "description": "Voucher create request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 255, "description": "comment (must be set when the voucher gets deleted)", "example": "deleted reason comment" } }, "required": [ "comment" ] } } } }, "responses": { "204": { "description": "The server successfully processed the request and is not returning any content.", "content": { "application/json": { "schema": { "type": "string", "example": "No Content" } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } } } } }, "/vouchers/{id}/complete": { "get": { "tags": [ "Vouchers" ], "summary": "Get a complete voucher", "description": "Use this call to get a voucher with its secret properties *code* and *pin*.", "security": [ { "BearerAuth": [ "read-secrets" ] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "da39a3ee3458b7392ef5" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "A unique custom identifier for this voucher (e.g. a sku). Also used for activation of this voucher. (optional, if not set for this voucher it will be auto generated based on the UI regex settings)", "maxLength": 255, "example": "4ZH83T0ACUUC14CW" }, "client_id": { "type": "string", "description": "id of the client that created this voucher", "readOnly": true, "example": "da39a3ee5eb28b7392ef5" }, "sku": { "type": "string", "maxLength": 255, "description": "Optional SKU", "example": "AJHS8675FG" }, "batch": { "type": "string", "maxLength": 30, "description": "Optional campaign or grouping identifier", "example": "Winter Campaign" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "currency": { "type": "string", "description": "The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "minLength": 3, "maxLength": 3, "example": "EUR" }, "valid_until": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "Date until which this voucher is valid and can be redeemed. Calculated based on validity_value and validity_interval on activation. This property will be null if the voucher is inactive.", "example": "2025-07-21T17:32:28+00:00" }, "validity_value": { "type": "integer", "description": "Calculates together with validity_interval the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": 24 }, "validity_interval": { "type": "string", "enum": [ "days", "weeks", "months", "years" ], "description": "Calculates together with validity_value the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": "months" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "The status of this voucher. In general vouchers are inactive when created, and gets activated when payed. Only activated vouchers can be charged.", "example": "active" }, "type": { "type": "string", "enum": [ "print", "digital" ], "description": "Defines if this voucher is printed or digital. Printed vouchers will have the status inactive by default.", "example": "digital" }, "taxable": { "type": "boolean", "description": "Defines if this voucher is a taxable multi purpose voucher", "example": true, "default": false }, "tax_rate": { "type": "string", "description": "The tax rate for this voucher (only required when taxable is true)", "example": "19" }, "order_number": { "type": "string", "description": "An optional order number for this voucher", "example": "Order 66" }, "data": { "type": "string", "description": "Any additional custom data for this voucher as a JSON string", "example": "{\"foo\": \"bar\"}" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } }, { "properties": { "code": { "type": "string", "maxLength": 255, "description": "A code that must be entered during the ordering process to receive the savings indidcated on the assiciated voucher. (optional, if not set a code for this voucher will be auto generated based on the UI regex settings)", "example": "test" }, "pin": { "type": "string", "maxLength": 255, "description": "An additional security feature (covered) on printed vouchers, due to the fact that the code itself must be visible on the outside for activation of the voucher.", "example": "test" } } } ] } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } } } } }, "/vouchers/{id}/status": { "patch": { "tags": [ "Vouchers" ], "summary": "Set the status for a voucher", "description": "This call is used to activate or deactivate a specific voucher.", "security": [ { "BearerAuth": [ "use" ] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "da39a3ee3458b7392ef5" } ], "requestBody": { "description": "Voucher status request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "new status", "example": "active" }, "comment": { "type": "string", "maxLength": 255, "description": "comment", "example": "reason for this status change" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique custom identifier for this voucher (e.g. a sku). Also used for activation of this voucher. (optional, if not set for this voucher it will be auto generated based on the UI regex settings)", "maxLength": 255, "example": "4ZH83T0ACUUC14CW" }, "client_id": { "type": "string", "description": "id of the client that created this voucher", "readOnly": true, "example": "da39a3ee5eb28b7392ef5" }, "sku": { "type": "string", "maxLength": 255, "description": "Optional SKU", "example": "AJHS8675FG" }, "batch": { "type": "string", "maxLength": 30, "description": "Optional campaign or grouping identifier", "example": "Winter Campaign" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "currency": { "type": "string", "description": "The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "minLength": 3, "maxLength": 3, "example": "EUR" }, "valid_until": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "Date until which this voucher is valid and can be redeemed. Calculated based on validity_value and validity_interval on activation. This property will be null if the voucher is inactive.", "example": "2025-07-21T17:32:28+00:00" }, "validity_value": { "type": "integer", "description": "Calculates together with validity_interval the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": 24 }, "validity_interval": { "type": "string", "enum": [ "days", "weeks", "months", "years" ], "description": "Calculates together with validity_value the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI)", "example": "months" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "The status of this voucher. In general vouchers are inactive when created, and gets activated when payed. Only activated vouchers can be charged.", "example": "active" }, "type": { "type": "string", "enum": [ "print", "digital" ], "description": "Defines if this voucher is printed or digital. Printed vouchers will have the status inactive by default.", "example": "digital" }, "taxable": { "type": "boolean", "description": "Defines if this voucher is a taxable multi purpose voucher", "example": true, "default": false }, "tax_rate": { "type": "string", "description": "The tax rate for this voucher (only required when taxable is true)", "example": "19" }, "order_number": { "type": "string", "description": "An optional order number for this voucher", "example": "Order 66" }, "data": { "type": "string", "description": "Any additional custom data for this voucher as a JSON string", "example": "{\"foo\": \"bar\"}" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } }, "422": { "description": "The request was well-formed but was unable to be followed due to semantic errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 422 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.CREATE.UNPROCESSABLE_ENTITY" }, "message": { "type": "string", "description": "The error message", "default": "The given data was invalid." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A unique code for this specific validation error", "example": "VOUCHER.CREATE.CURRENCY.VALID_CURRENCY" }, "property": { "type": "string", "description": "The property where the validation fails", "example": "currency" }, "rule": { "type": "string", "description": "The rule that caused the validation fail", "example": "valid_currency" }, "message": { "type": "string", "description": "The validation rule error message", "example": "Currency must be a valid currency code" } } } } } } } } } } } }, "/reservations": { "post": { "tags": [ "Reservations" ], "summary": "Set the reservation for a specific voucher", "description": "This call temporary reserves an amount on a specific voucher, that can later be charged.\nA reservation expires after 30 minutes or in case a new one is requested for this voucher.\n", "security": [ { "BearerAuth": [ "use" ] } ], "requestBody": { "description": "Voucher reservation request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "currency": { "type": "string", "description": "The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes (must match the currency of the voucher)", "minLength": 3, "maxLength": 3, "example": "EUR" }, "code": { "type": "string", "maxLength": 255, "description": "A code that must be entered during the ordering process to receive the savings indidcated on the assiciated voucher.", "example": "test" }, "pin": { "type": "string", "maxLength": 255, "description": "An additional security feature on printed vouchers", "example": "test" } }, "required": [ "amount", "currency", "code" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identification key - will be used in voucher-reservation calls", "readOnly": true, "example": "da39a3ee5eb28b7392ef5" }, "voucher_id": { "type": "string", "description": "Voucher primary identification key (see voucher -> id)", "readOnly": true, "example": "da39a3ee4528b7392ef5" }, "voucher_taxable": { "type": "boolean", "description": "Defines if this voucher is a taxable multi purpose voucher", "example": false }, "voucher_tax_rate": { "type": "string", "description": "The tax rate for this voucher (only needed when taxable is true, can also be null)", "example": null }, "client_id": { "type": "string", "description": "Client primary identification key (see client -> id)", "readOnly": true, "example": "cff8784e5eb28b9b04860" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "valid_until": { "type": "string", "format": "RFC3339", "description": "valid_until - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } } } } }, "403": { "description": "The request contained valid data and was understood by the server, but the server is refusing action.", "content": { "application/json": { "schema": { "type": "string", "example": "Forbidden" } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } }, "422": { "description": "The request was well-formed but was unable to be followed due to semantic errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 422 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.CREATE.UNPROCESSABLE_ENTITY" }, "message": { "type": "string", "description": "The error message", "default": "The given data was invalid." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A unique code for this specific validation error", "example": "VOUCHER.CREATE.CURRENCY.VALID_CURRENCY" }, "property": { "type": "string", "description": "The property where the validation fails", "example": "currency" }, "rule": { "type": "string", "description": "The rule that caused the validation fail", "example": "valid_currency" }, "message": { "type": "string", "description": "The validation rule error message", "example": "Currency must be a valid currency code" } } } } } } } } } } } }, "/reservations/{id}/charge": { "post": { "tags": [ "Reservations" ], "summary": "Charge a specific voucher reservation", "description": "Charges the previously created temporary reservation on a voucher.", "security": [ { "BearerAuth": [ "use" ] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "da39a3ee3458b7392ef5" } ], "requestBody": { "description": "Voucher charge request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_number": { "type": "string", "description": "Order or invoice number of the transaction for this usage", "example": "ORDER-62642" } }, "required": [ "order_number" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identification key - will be used in voucher-charge calls", "readOnly": true, "example": "cff8784e5eb28b9b04860" }, "voucher_id": { "type": "string", "description": "Voucher primary identification key (see voucher -> id)", "readOnly": true, "example": "cff8784e34b28b9b04860" }, "client_id": { "type": "string", "description": "Client primary identification key (see client -> id)", "readOnly": true, "example": "cff8784e5eb28b81ca02a" }, "type": { "type": "string", "enum": [ "charge", "recharge", "refund" ], "description": "Type of this charge. Can either be \"charge\", \"recharge\" or \"refund\"", "readOnly": true, "example": "charge" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "order_number": { "type": "string", "description": "Order or invoice number of the transaction", "example": "ORDER-62642" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } } } } }, "403": { "description": "The request contained valid data and was understood by the server, but the server is refusing action.", "content": { "application/json": { "schema": { "type": "string", "example": "Forbidden" } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } }, "422": { "description": "The request was well-formed but was unable to be followed due to semantic errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 422 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.CREATE.UNPROCESSABLE_ENTITY" }, "message": { "type": "string", "description": "The error message", "default": "The given data was invalid." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A unique code for this specific validation error", "example": "VOUCHER.CREATE.CURRENCY.VALID_CURRENCY" }, "property": { "type": "string", "description": "The property where the validation fails", "example": "currency" }, "rule": { "type": "string", "description": "The rule that caused the validation fail", "example": "valid_currency" }, "message": { "type": "string", "description": "The validation rule error message", "example": "Currency must be a valid currency code" } } } } } } } } } } } }, "/vouchers/{id}/charges": { "get": { "tags": [ "Vouchers" ], "summary": "Get a list of voucher charges", "description": "This call will give you a paginated list of voucher charges.", "security": [ { "BearerAuth": [ "read" ] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "da39a3ee3458b7392ef5" }, { "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 2 }, { "in": "query", "name": "per_page", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 25 }, "example": 10 }, { "in": "query", "name": "filter[created_from]", "required": false, "schema": { "type": "string", "format": "RFC3339" }, "example": "2017-07-21T17:32:28+00:00", "description": "Sets a filter to get all entries from this datetime - must be set in RFC3339 format, see https://tools.ietf.org/html/rfc3339" }, { "in": "query", "name": "filter[created_to]", "required": false, "schema": { "type": "string", "format": "RFC3339" }, "example": "2017-07-21T17:32:28Z+00:00", "description": "Sets a filter to get all entries up to this datetime - must be set in RFC3339 format, see https://tools.ietf.org/html/rfc3339" }, { "in": "query", "name": "filter[order_number]", "required": false, "schema": { "type": "string" }, "style": "form", "example": "ORDER66", "description": "Sets a filter to get all entries with a specific order number" }, { "in": "query", "name": "filter[amount]", "required": false, "schema": { "type": "string" }, "style": "form", "example": "10.50", "description": "Sets a filter to get all entries with a specific amount" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identification key - will be used in voucher-charge calls", "readOnly": true, "example": "cff8784e5eb28b9b04860" }, "voucher_id": { "type": "string", "description": "Voucher primary identification key (see voucher -> id)", "readOnly": true, "example": "cff8784e34b28b9b04860" }, "client_id": { "type": "string", "description": "Client primary identification key (see client -> id)", "readOnly": true, "example": "cff8784e5eb28b81ca02a" }, "type": { "type": "string", "enum": [ "charge", "recharge", "refund" ], "description": "Type of this charge. Can either be \"charge\", \"recharge\" or \"refund\"", "readOnly": true, "example": "charge" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "order_number": { "type": "string", "description": "Order or invoice number of the transaction", "example": "ORDER-62642" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } } } } }, { "type": "object", "properties": { "links": { "type": "object", "properties": { "first": { "type": "string", "maxLength": 255, "description": "First page link", "example": "http://domain/v1/vouchers?page=1" }, "last": { "type": "string", "maxLength": 255, "description": "Last page link", "example": "http://domain/v1/vouchers?page=5" }, "prev": { "type": "string", "nullable": true, "maxLength": 255, "description": "Previous page link", "example": "http://domain/v1/vouchers?page=3" }, "next": { "type": "string", "nullable": true, "maxLength": 255, "description": "Next page link", "example": "http://domain/v1/vouchers?page=2" } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1, "description": "Current page", "example": 1 }, "per_page": { "type": "integer", "minimum": 1, "description": "Limit per page", "example": 15 }, "from": { "type": "integer", "minimum": 1, "nullable": true, "description": "Start of pagination", "example": 1 }, "to": { "type": "integer", "minimum": 1, "nullable": true, "description": "Start of pagination", "example": 15 }, "last_page": { "type": "integer", "minimum": 1, "description": "Last page", "example": 167 }, "total": { "type": "integer", "minimum": 1, "description": "Total pages count", "example": 2500 }, "path": { "type": "string", "maxLength": 255, "description": "Current path link", "example": "http://domain/v1/vouchers" } } } } } ] } } } } } } }, "/vouchers/{id}/charges/{charge_id}": { "get": { "tags": [ "Vouchers" ], "summary": "Get a charge of a voucher", "description": "Use this call to get a specific charge of a voucher.", "security": [ { "BearerAuth": [ "read" ] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "da39a3ee3458b7392ef5" }, { "in": "path", "name": "charge_id", "required": true, "schema": { "type": "string", "example": "da39a3ee5eb28b7392ef5" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identification key - will be used in voucher-charge calls", "readOnly": true, "example": "cff8784e5eb28b9b04860" }, "voucher_id": { "type": "string", "description": "Voucher primary identification key (see voucher -> id)", "readOnly": true, "example": "cff8784e34b28b9b04860" }, "client_id": { "type": "string", "description": "Client primary identification key (see client -> id)", "readOnly": true, "example": "cff8784e5eb28b81ca02a" }, "type": { "type": "string", "enum": [ "charge", "recharge", "refund" ], "description": "Type of this charge. Can either be \"charge\", \"recharge\" or \"refund\"", "readOnly": true, "example": "charge" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "order_number": { "type": "string", "description": "Order or invoice number of the transaction", "example": "ORDER-62642" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } } } } }, "/charges/{id}/refund": { "post": { "tags": [ "Charges" ], "summary": "Refund a specific voucher charge", "description": "This call is used to (partial) refund a specific charge that was previously done on a voucher (for example if a customer returns goods to the store).", "security": [ { "BearerAuth": [ "use" ] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "example": "da39a3ee3458b7392ef5" } ], "requestBody": { "description": "Voucher refund request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Greater or equal than 0.01\n* Less than the Charge Amount\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "currency": { "type": "string", "description": "The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes (must match the currency of the voucher)", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identification key - will be used in voucher-charge calls", "readOnly": true, "example": "cff8784e5eb28b9b04860" }, "voucher_id": { "type": "string", "description": "Voucher primary identification key (see voucher -> id)", "readOnly": true, "example": "cff8784e34b28b9b04860" }, "client_id": { "type": "string", "description": "Client primary identification key (see client -> id)", "readOnly": true, "example": "cff8784e5eb28b81ca02a" }, "type": { "type": "string", "enum": [ "charge", "recharge", "refund" ], "description": "Type of this charge. Can either be \"charge\", \"recharge\" or \"refund\"", "readOnly": true, "example": "charge" }, "amount": { "type": "string", "minLength": 4, "maxLength": 9, "pattern": "^\\d+\\.\\d{2}$", "description": "Amount in the currency of this voucher. Must be send as string in the following pattern:\n* Up to five digits before the decimal point\n* The decimal point (.)\n* Exactly two digits after the decimal point\n", "example": "10.53" }, "order_number": { "type": "string", "description": "Order or invoice number of the transaction", "example": "ORDER-62642" }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" } } }, { "properties": { "type": { "example": "refund" } } } ] } } } }, "403": { "description": "The request contained valid data and was understood by the server, but the server is refusing action.", "content": { "application/json": { "schema": { "type": "string", "example": "Forbidden" } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } }, "422": { "description": "The request was well-formed but was unable to be followed due to semantic errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 422 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.CREATE.UNPROCESSABLE_ENTITY" }, "message": { "type": "string", "description": "The error message", "default": "The given data was invalid." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A unique code for this specific validation error", "example": "VOUCHER.CREATE.CURRENCY.VALID_CURRENCY" }, "property": { "type": "string", "description": "The property where the validation fails", "example": "currency" }, "rule": { "type": "string", "description": "The rule that caused the validation fail", "example": "valid_currency" }, "message": { "type": "string", "description": "The validation rule error message", "example": "Currency must be a valid currency code" } } } } } } } } } } } }, "/clients/connect": { "post": { "tags": [ "Clients" ], "summary": "Connects a client", "description": "Exchanges temporary pin for full oauth client credentials", "security": [], "requestBody": { "description": "Client connect request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pin": { "type": "string", "maxLength": 255, "description": "Previously temporarily issued PIN from the Voucher Admin UI (30 minutes validity)", "example": "X53HI0" } }, "required": [ "pin" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identification key - will be used in client calls", "readOnly": true, "example": "da39a3ee5eb28b7392ef5" }, "client_group_id": { "type": "string", "description": "Primary identification key from the selected group (id)", "readOnly": false, "example": "cff8784e5eb28b81ca02a" }, "name": { "type": "string", "maxLength": 255, "description": "Naming or description of the client", "example": "Test-Client" }, "secret": { "type": "string", "maxLength": 255, "description": "secret", "example": "VrhgrKVDTqjg1GVr3R6Juvx7FfHQK7Psim7ORAXm" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "can_use", "can_manage" ] } }, "created_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "updated_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "connected_at": { "type": "string", "format": "RFC3339", "readOnly": true, "description": "connected_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339", "example": "2017-07-21T17:32:28+00:00" }, "type": { "type": "string", "readOnly": true, "description": "The type of this client", "example": "pos" } } } } } }, "401": { "description": "Invalid pin or client was already registered", "content": { "application/json": { "schema": { "type": "string", "example": "Invalid pin or client was already registered" } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } }, "422": { "description": "The request was well-formed but was unable to be followed due to semantic errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 422 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.CREATE.UNPROCESSABLE_ENTITY" }, "message": { "type": "string", "description": "The error message", "default": "The given data was invalid." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A unique code for this specific validation error", "example": "VOUCHER.CREATE.CURRENCY.VALID_CURRENCY" }, "property": { "type": "string", "description": "The property where the validation fails", "example": "currency" }, "rule": { "type": "string", "description": "The rule that caused the validation fail", "example": "valid_currency" }, "message": { "type": "string", "description": "The validation rule error message", "example": "Currency must be a valid currency code" } } } } } } } } } } } }, "/clients/disconnect": { "post": { "tags": [ "Clients" ], "summary": "Disconnects a client", "description": "Disconnects the client from the voucher cloud and resets all credentials", "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "The server successfully processed the request and is not returning any content.", "content": { "application/json": { "schema": { "type": "string", "example": "No Content" } } } }, "404": { "description": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "The HTTP status code", "default": 404 }, "code": { "type": "string", "description": "A unique code for this error", "example": "VOUCHER.NOT_FOUND" }, "message": { "type": "string", "description": "The error message", "example": "The requested Voucher was not found." } } } } } } } } } } }