Overview

This page outlines the parts of Convious API solution and describes the various resources that you will be interacting with to integrate with us.

Terms of Service

Authentication

To authorize, append HTTP Authorization header to your request:

curl "<api_endpoint_here>"
  -H "Authorization: Bearer <access_token_here>"

You will have to authenticate in order to make almost any request to our API. Regardless of the API used, the authentication mechanism is always the same. If you do not provide credentials or provide incorrect ones, a HTTP status code 401 will be returned.

Obtaining access token

curl -X POST \
    -d 'grant_type=client_credentials' \
    -d 'client_id=<client_id>' \
    -d 'client_secret=<client_secret>' \
    https://identity.convious.com/oauth/token/

The request will return a JSON response of the following format:

{
  "token_type": "Bearer",
  "access_token": "<access_token>"
}

Access tokens are issued by our OAUTH2 server. To get a token, use OAUTH2 client_credentials flow.

HTTP Request

POST https://identity.convious.com/oauth/token/

Post Data

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

You must replace the client_id and client_secret with your client id and client secret. If you do not know your client id and/or secret, please contact us.

The data is posted using application/x-www-form-urlencoded content type.

Response

Field	Type	Description
token_type	string	Always 'Bearer'
access_token	string	Token that you should use in your HTTP `Authorization` header

Orders API

Order Type

Several endpoints make use of this type in their responses. The actual data returned depends on what include options were selected (see documentation of endpoints themselves for more details). This documentation provides an example of how an order payload looks like with everything included.

{
  "id": "f262d704-a7a0-45b3-af0f-920b3de9ec5a",
  "number": "95802491",
  "account": "convious_demo",
  "status": "confirmed",
  "productType": "tickets",
  "categoryId": "ce68fff6-4ce9-4996-b5d1-1020baf7d0ad",
  "orderDate": "2021-12-31T23:01:10.647104 | 00:00",
  "updatedAt": "2022-01-03T06:22:41.040608 | 00:00",
  "visitDate": "2022-01-04",
  "visitTime": "13:00:00",
  "visitEndTime": "14:00:00",
  "timezone": "Europe/Amsterdam",
  "ticketDownloadUrl": "https://api.convious-app.com/api/v1/cart/order/download/4976476/f262d704-a7a0-45b3-af0f-920b3de9ec5a/",
  "quantity": 4,
  "total": "49.20",
  "totalPriceInclTax": "49.20",
  "totalAfterDiscount": "49.20",
  "totalDiscountedPriceInclTax": "49.20",
  "totalDiscountedPriceExclTax": "48.37",
  "discountAmount": "0",
  "currency": "EUR",
  "locationId": "d70aed5a-3960-44fa-9c08-f725c2b03ce8",
  "emailStatus": "opened",
  "unfilledApf": false,
  "unfilledApfUrl": null,
  "printed": null,
  "downloaded": null,
  "externalId": null,
  "orderSource": "api",
  "madeBy": "",
  "customer": {
    "email": "demo | syfdg@ticketoo.nl",
    "language": "EN",
    "marketingOptIn": false
  },
  "items": [
    {
      "id": "f06afed5-a5ac-4fac-95e9-ce05c3089b46",
      "orderItemId": "3523249e-bc00-4e58-b1b0-31220531bc60",
      "productId": "0bda54d3-072e-425a-8d07-584515eb2fe7",
      "product": "Parking Ticket",
      "gatePrice": "6.00",
      "gatePriceInclTax": "6.00",
      "gatePriceExclTax": "",
      "pricePerItem": "5.00",
      "priceInclTax": "5.00",
      "priceExclTax": "4.17",
      "pricePerItemAfterDiscount": "5.00",
      "discountedPriceInclTax": "5.00",
      "discountedPriceExclTax": "4.17",
      "pricePerItemWithoutOptionsAfterDiscount": "5.00",
      "discountedPriceWithoutOptionsInclTax": "5.00",
      "discountedPriceWithoutOptionsExclTax": "4.17",
      "invalidatedAt": null,
      "validFrom": "2022-01-04T00:00:00 | 00:00",
      "validTo": "2022-01-04T23:59:59.999999 | 00:00",
      "refunded": false,
      "canRefund": true,
      "isBundle": false,
      "afterPaymentForm": {
        "name": "Lynda Hegmann III",
        "phone": "430730457"
      },
      "printed": "2022-01-04",
      "downloaded": "2022-01-04",
      "status": "paid",
      "barcode": {
        "type": "code128",
        "barcode": "86663260686492",
        "status": "available",
        "scanLimit": "once",
        "scanLimitTimes": 1,
        "redeemed": null
      },
      "discounts": [
        {
          "code": "54647232687379",
          "type": "InHouseBarcode",
          "name": "reservation",
          "amount": "0.00",
          "externalId": null
        }
      ],
      "externalIds": {
        "account": {},
        "product": {}
      },
      "options": [
        {
          "name": "First row parking",
          "numberOfItems": 1,
          "price": "0.00",
          "priceInclTax": "0.00",
          "priceExclTax": "0.00",
          "taxes": [
            {
              "priceProportionPercentage": "100.00",
              "taxAmount": "0.00",
              "taxPercentage": "19.00",
              "type": "VAT",
              "taxableAmount": "0.00"
            }
          ]
        }
      ],
      "refundDetails": {
        "itemName": "Parking Ticket",
        "itemPriceInclTax": "5.00",
        "itemUuid": "3523249e-bc00-4e58-b1b0-31220531bc60",
        "orderNumber": "95802491",
        "conviousRefundFee": null,
        "partnerRefundFee": 0.0,
        "refundReason": "bad weather",
        "refundedBy": "123@ticketoo.nl",
        "eventDate": "2022-01-04",
        "paymentDate": "2021-12-31T23:01:32.324472Z",
        "refundedAt": "2022-01-05T08:48:22.346553Z",
        "refundFeeType": "absolute"
      },
      "taxes": [
        {
          "priceProportionPercentage": "100.00",
          "taxAmount": "0.83",
          "taxPercentage": "20.00",
          "type": "VAT",
          "taxableAmount": "5.00"
        }
      ]
    }
  ],
  "discounts": [
    {
      "code": "54647232687379",
      "type": "InHouseBarcode",
      "name": "reservation",
      "amount": "0.00",
      "externalId": null
    }
  ],
  "location": {
    "id": "d70aed5a-3960-44fa-9c08-f725c2b03ce8",
    "name": "Amsterdam"
  },
  "reseller": {
    "id": null,
    "name": null
  },
  "payments": [
    {
      "id": 6351596,
      "paymentProvider": "Mollie",
      "paymentMethod": "creditcard",
      "paymentStatus": "paid",
      "paymentDate": "2021-12-31T23:01:29.820951 | 00:00"
    }
  ]
}

Fields

Field	Type	Description
`id`	UUID	An id of the order
`number`	string	A human friendly identifier of the order. Uniquely identifies the order and is often used by for communication with customers.
`account`	string	An account slug of the account for which the order was made
`status`	string	The status of the order. One of: `open`, `confirmed`, `cancelled`
`productType`	string	A type of product(s) that have been sold with this order. Possible values: `tickets` or `date_change`
`categoryId`	UUID	Category id of products in this order
`orderDate`	datetime	An ISO8601 datetime of when the order was created.
`updatedAt`	datetime	An ISO8601 datetime of when the order was updated.
`visitDate`	date	An ISO8601 date of when the visit should take place with the tickets purchased. Null if tickets are not dated.
`visitTime`	time	A time in venue's timezone of when the visit should take place with the tickets purchased. Null if tickets are not dated or if this a full day event.
`visitEndTime`	time	A time in venue's timezone of when the visit should end with the tickets purchased. Null if tickets are not dated, this a full day event or no end time was specified.
`timezone`	string	Timezone identifier of the venue for which the order is for.
`ticketDownloadUrl`	url	A url that can be used to download the ticket pdf for this order.
`quantity`	number	The number of tickets in this order.
`total`	number as string	DEPRECATED. Use `totalPriceInclTax` instead.
`totalPriceInclTax`	number as string	Total non discounted value of items in this order including tax.
`totalPriceExclTax`	number as string	Total non discounted value of items in this order excluding tax.
`totalAfterDiscount`	number as string	DEPRECATED. Use `totalDiscountedPriceInclTax` instead.
`totalDiscountedPriceInclTax`	number as string	Total value of items including tax in this order after discount codes were applied.
`totalDiscountedPriceExclTax`	number as string	Total value of items excluding tax in this order after discount codes were applied.
`discountAmount`	number as string	Total amount that was discounted in this order.
`currency`	string	The currency of the order.
`locationId`	UUID	An id of the venue's location.
`emailStatus`	string	Status of the order confirmation email. Possible values: `sending`, `processed`, `delivered`, `opened`, `clicked`, `deferred`, `bounced`, `dropped`, `disabled`
`unfilledApf`	boolean	True if the after payment form needs to be filled in for this order (e.g. form is enabled for this order and the customer has not filled it in yet).
`unfilledApfUrl`	url	A url that can be used to fill in the after payment form for this order
`printed`	datetime	An ISO8601 datetime of when the ticket pdf was printed for this order. Null if it was never printed.
`downloaded`	datetime	An ISO8601 datetime of when the ticket pdf was downloaded for this order. Null if it was never downloaded.
`externalId`	string	External id for this order.
`orderSource`	string	The sales channel that the order originated from.
`madeBy`	string	The order created by user.
`customer`	Customer	Customer information for this order. Only part of payload if customer information is added to inclusions.
`customer.email`	string	Email of the customer.
`customer.language`	string	Language that the customer has selected.
`customer.marketingOptIn`	boolean	Whether the customer has opted in for marketing emails.
`items`	Ticket[]	A list of tickets included in this order. Only part of the payload if items is added to inclusions.
`items.id`	UUID	Id of the ticket.
`items.orderItemId`	UUID	Id of the order item in the order. For example if the order contained 2 adult and a child ticket, then 2 adults would have the same order item id while the child one would have a different one.
`items.productId`	UUID	Id of the product that was sold.
`items.product`	string	Name of the product that was sold.
`items.gatePrice`	number as string	DEPRECATED. Use `items.gatePriceInclTax` instead.
`items.gatePriceInclTax`	number as string	The price including tax at which the product is sold at the gate of the venue. Empty if partners show price without taxes.
`items.gatePriceExclTax`	number as string	The price excluding tax at which the product is sold at the gate of the venue. Empty if partners show price with taxes.
`items.pricePerItem`	number as string	DEPRECATED. Use `items.priceInclTax` instead.
`items.priceInclTax`	number as string	The price of the ticket, including tax, before any discounts were applied.
`items.priceExclTax`	number as string	The price of the ticket, excluding tax, before any discounts were applied.
`items.pricePerItemAfterDiscount`	number as string	DEPRECATED. Use `items.discountedPriceInclTax` instead.
`items.discountedPriceInclTax`	number as string	The price of the ticket, including tax, after the discounts were applied.
`items.discountedPriceExclTax`	number as string	The price of the ticket, excluding tax, after the discounts were applied.
`items.pricePerItemWithoutOptionsAfterDiscount`	number as string	DEPRECATED. Use `items.discountedPriceWithoutOptionsInclTax` instead.
`items.discountedPriceWithoutOptionsInclTax`	number as string	The price of the ticket, including tax but excluding ticket options, after the discounts were applied.
`items.discountedPriceWithoutOptionsExclTax`	number as string	The price of the ticket, excluding tax and ticket options, after the discounts were applied.
`items.invalidatedAt`	datetime	An ISO8601 datetime of when this ticket got invalidated (due to a cancellation or a refund).
`items.validFrom`	datetime	An ISO8601 datetime of when this ticket is valid from (e.g. can be scanned).
`items.validTo`	datetime	An ISO8601 datetime of when this ticket is until from (e.g. can be scanned).
`items.refunded`	boolean	Indicates if the ticket has been refunded.
`items.canRefund`	boolean	Indicates if the ticket can be refunded.
`items.isBundle`	boolean	Indicates if the ticket is part of a bundle.
`items.afterPaymentForm`	key-value pairs	After payment form information that has been filled in for this specific ticket.
`items.printed`	date	An ISO8601 date of when the ticket pdf was printed. Null if it was never printed.
`items.downloaded`	date	An ISO8601 date of when the ticket pdf was downloaded. Null if it was never downloaded.
`items.status`	string	Status of the ticket.
`items.barcode`	Barcode	Barcode information for this ticket. Only part of the payload if barcodes are added to inclusions.
`items.barcode.type`	string	Type of the barcode
`items.barcode.barcode`	string	The barcode for this ticket.
`items.barcode.status`	string	Status of this barcode. One of: `available` or `redeemed`.
`items.barcode.scanLimit`	string	Scan limit of this barcode. One of: `none` (can be scanned unlimited amount of times), `once` (can be scanned once) or `times_per_day` (can be scanned only a specified times per day).
`items.barcode.scanLimitTimes`	number	Number of times this barcode can be scanned per day (if applicable).
`items.barcode.redeemed`	datetime	An ISO8601 datetime of when the barcode of this ticket has been redeemed.
`items.discounts`	Discount[]	Discounts applied to this ticket. Only part of the payload if discounts are added to inclusions.
`items.discounts.code`	string	The discount code used for this ticket
`items.discounts.type`	string	The discount type used for this ticket
`items.discounts.name`	string	The discount name used for this ticket
`items.discounts.amount`	number as string	The discount amount used for this ticket.
`items.discounts.externalId`	string	External id for this discount.
`items.externalIds`	ExternalIds	External ids related to this ticket. Only part of the payload if external ids are added to inclusions.
`items.externalIds.account`	key-value pairs	Account related external ids of this ticket. The key is the integration type while the value is the external id.
`items.externalIds.product`	key-value pairs	Product related external ids of this ticket. The key is the integration type while the value is the external id.
`items.options`	Options[]	Product related options of this ticket. Product option can have separate price and taxes. Only part if the payload if options are added to inclusions
`items.options.name`	string	Name of the ticket option
`items.options.numberOfItems`	integer	Number of this option sold together with the ticket
`items.options.price`	number as string	DEPRECATED. Use `items.options.priceInclTax` instead.
`items.options.priceInclTax`	number as string	The price of the ticket option, including tax, before any discounts were applied.
`items.options.priceExclTax`	number as string	The price of the ticket option, excluding tax, before any discounts were applied.
`items.options.taxes`	Taxes[]	Taxes related to this ticket option. Only part of the payload if taxes are added to inclusions
`items.options.taxes.priceProportionPercentage`	number as string	Percentage of option price the tax was calculated on.
`items.options.taxes.taxAmount`	number as string	Calculated amount of the tax.
`items.options.taxes.taxPercentage`	number as string	Tax percentage.
`items.options.taxes.type`	string	Type of the tax.
`items.options.taxes.taxableAmount`	number as string	The price on which tax is calculated.
`items.refundDetails`	RefundDetails	Information regarding the refund process for the ticket.
`items.refundDetails.itemName`	string	The name of the product associated with the refund.
`items.refundDetails.itemPriceInclTax`	number as string	The price of the ticket option, including tax, before any discounts were applied.
`items.refundDetails.itemUuid`	UUID	The unique identifier (UUID) of the refunded product.
`items.refundDetails.orderNumber`	string	A user-friendly identifier for the order.
`items.refundDetails.conviousRefundFee`	number	The refund fee charged by Convious.
`items.refundDetails.partnerRefundFee`	number	The refund fee charged by the partner.
`items.refundDetails.refundReason`	string	The reason provided for issuing the refund.
`items.refundDetails.refundedBy`	string	The user who initiated/approved the refund.
`items.refundDetails.eventDate`	date	The scheduled date of the event or visit, formatted as an ISO8601 date.
`items.refundDetails.paymentDate`	datetime	The date and time when the payment was made, in ISO8601 format.
`items.refundDetails.refundedAt`	datetime	The date and time when the refund was processed, in ISO8601 format.
`items.refundDetails.refundFeeType`	string	The type of the refund fee applied. One of: `absolute` or `percentage`.
`items.taxes`	Taxes[]	Taxes related to this ticket. Ticket option taxes are not included to this list. Only part of the payload if taxes are added to inclusions
`items.taxes.priceProportionPercentage`	number as string	Percentage of price the tax was calculated on.
`items.taxes.taxAmount`	number as string	Calculated amount of the tax.
`items.taxes.taxPercentage`	number as string	Tax percentage.
`items.taxes.type`	string	Type of the tax.
`items.taxes.taxableAmount`	number as string	The price on which tax is calculated.
`discounts`	Discount[]	Discounts applied to this order. Only part of the payload if discounts are added to inclusions.
`discounts.code`	string	The discount code used for this order.
`discounts.type`	string	Type for this discount.
`discounts.name`	string	Name of the discount.
`discounts.amount`	number as string	The amount of the discount.
`discounts.externalId`	string	External id for this discount.
`location`	Location	Information about the venue's location. Only part of the payload if location information is added to inclusions.
`location.id`	UUID	An id of the venue's location.
`location.name`	string	The name of the venue's location.
`reseller`	Reseller	Information about the reseller that has made the order. Only part of the payload if reseller information is added to inclusions.
`reseller.id`	string	Id of the reseller.
`reseller.name`	string	The name of the reseller.
`payments`	Payment[]	Payments associated with this order. Only part of the payload if payments are added to inclusions.
`payments.id`	number	The payment id.
`payments.paymentProvider`	string	Payment provider used for this order.
`payments.paymentMethod`	string	Payment method used for this order.
`payments.paymentStatus`	string	The status of the payment. One of: `open`, `paid`, `refunded`, `charged_back`
`payments.paymentDate`	datetime	The date of the payment.

Getting orders timeline

Use case

This endpoint can be used to:

Import all orders that were made in Convious system
React to any changes to the orders (e.g. order got paid or refunded)

Intended way of using orders timeline

This endpoint returns all the orders that were created or modified since some moment in time. The integrating system should:

Initially call this endpoint with either no timestamp or a timestamp in far enough past to include all the orders made by Convious. Alternatively, current time can be used as the initial value to instead process only orders made from now on.
Process every page of returned output. Take note of updatedAt of the last order in the payload and store it.
After a while, call this endpoint with previously stored timestamp to get order changes since last call and process those, again storing updatedAt of the last order in the payload.
Repeat step 3 indefinitely

This endpoint can be used to retrieve every single order made in Convious system every time, however, we do not recommend this, because the order list will get bigger and bigger each time, making it increasingly difficult to process.

Keep in mind that the same order can be returned multiple times between calls (each time because it got updated for different reasons), so the integrating system should make use of order ids to ensure that orders are not duplicated. For example, you may receive an order which was freshly made, then 10 minutes later receive it again because it got paid and then the next day receive it again because it got refunded.

HTTP Request

GET https://api.convious.com/api/v1/orders/?account=<account_slug>&order_number=<order_number_filter>&email=<customer_email_filter>&from_updated_at=<update_timestamp>&status=<order_status_filter>&product_type=<product_type_filter>&from_visit_date=<visit_date_from_date>&to_visit_date=<visit_date_to_date>&products=<list_if_product_uuids>&reseller_id=<reseller_id>&include=<inclusions>

Query Parameters

Parameter	Required	Description
`account`	Permission dependent	Account slug to retrieve orders for. Required in most cases, if omitted, returns orders of every account.
`order_number`	No	Used to filter returned order by number.
`email`	No	Used to filter returned orders by email. For `+` sign usage in email, need to URL encode it to `%2b`.
`from_updated_at`	No	An ISO8601 datetime that is used to return only orders created or updated since this moment in time. If omitted, returns every order
`status`	No	Used to filter returned orders by their status. Accepted values are: `open`, `confirmed` and `cancelled`. Multiple values can be provided as a comma separated list.
`product_type`	No	Used to filter returned orders by product type. Accepted values are: `tickets` or `date_change`
`from_visit_date`	No	An ISO8601 date used to filter orders with visitDate since given date. If used, returns only orders with visitDate
`to_visit_date`	No	An ISO8601 date used to filter orders with visitDate up to and including given date. If used, returns only orders with visitDate
`products`	No	Used to filter returned orders by product `UUID`. Multiple values can be provided as a comma separated list
`reseller_id`	No	Used to filter returned orders by their reseller id.
`include`	No	Comma separated list of related entities included in the order. Possible inclusions:
		- `items` - includes tickets in the order
		- `items.barcode` - includes barcode information for each ticket. If supplied, also includes `items`
		- `items.external_ids` - includes all external ids associated with each ticket. If supplied, also includes `items`
		- `items.options` - includes options information of each order
		- `items.refund_details` - includes detailed refund information of each order
		- `items.taxes` - includes taxes information of each order
		- `customer` - includes customer information of each order
		- `discounts` - includes discount codes used in each order
		- `location` - includes location information of each order
		- `reseller` - includes reseller information of each order
		- `payments` - includes payment information of each order

Example output

Output received depends on include query parameter. This documentation provides an example payload of a response with every entity included.

{
    "next": "https://api.convious.com/api/v1/orders/?account=convious_demo&cursor=cD0yMDIyLTAxLTAyKzE4JTNBMzQlM0ExNS42NTE4NDElMkIwMCUzQTAw&from_updated_at=2022-01-01T00%3A00&include=items%2Citems.barcode%2Citems.external_ids%2Ccustomer%2Cdiscounts%2Creseller%2Clocation%2Cpayments&page_size=1",
    "previous": null,
    "results": [{
        "id": "f262d704-a7a0-45b3-af0f-920b3de9ec5a",
        "number": "95802491",
        "account": "convious_demo",
        "status": "confirmed",
        "productType": "tickets",
        "categoryId": "ce68fff6-4ce9-4996-b5d1-1020baf7d0ad",
        "orderDate": "2021-12-31T23:01:10.647104 | 00:00",
        "updatedAt": "2022-01-03T06:22:41.040608 | 00:00",
        "visitDate": "2022-01-04",
        "visitTime": "13:00:00",
        "visitEndTime": "14:00:00",
        "timezone": "Europe/Amsterdam",
        "ticketDownloadUrl": "https://api.convious-app.com/api/v1/cart/order/download/4976476/f262d704-a7a0-45b3-af0f-920b3de9ec5a/",
        "quantity": 4,
        "total": "49.20",
        "totalPriceInclTax": "49.20",
        "totalAfterDiscount": "49.20",
        "totalDiscountedPriceInclTax": "49.20",
        "totalDiscountedPriceExclTax": "48.37",
        "discountAmount": "0",
        "currency": "EUR",
        "locationId": "d70aed5a-3960-44fa-9c08-f725c2b03ce8",
        "emailStatus": "opened",
        "unfilledApf": false,
        "unfilledApfUrl": null,
        "printed": null,
        "downloaded": null,
        "externalId": null,
        "orderSource": "api",
        "madeBy": "",
        "customer": {
            "email": "demo | syfdg@ticketoo.nl",
            "language": "EN",
            "marketingOptIn": false
        },
        "items": [
            {
                "id": "f06afed5-a5ac-4fac-95e9-ce05c3089b46",
                "orderItemId": "3523249e-bc00-4e58-b1b0-31220531bc60",
                "productId": "0bda54d3-072e-425a-8d07-584515eb2fe7",
                "product": "Parking Ticket",
                "gatePrice": "6.00",
                "gatePriceInclTax": "6.00",
                "gatePriceExclTax": "",
                "pricePerItem": "5.00",
                "priceInclTax": "5.00",
                "priceExclTax": "4.17",
                "pricePerItemAfterDiscount": "5.00",
                "discountedPriceInclTax": "5.00",
                "discountedPriceExclTax": "4.17",
                "pricePerItemWithoutOptionsAfterDiscount": "5.00",
                "discountedPriceWithoutOptionsInclTax": "5.00",
                "discountedPriceWithoutOptionsExclTax": "4.17",
                "invalidatedAt": null,
                "validFrom": "2022-01-04T00:00:00 | 00:00",
                "validTo": "2022-01-04T23:59:59.999999 | 00:00",
                "refunded": false,
                "canRefund": true,
                "isBundle": false,
                "afterPaymentForm": {
                    "name": "Lynda Hegmann III",
                    "phone": "430730457"
                },
                "printed": "2022-01-04",
                "downloaded": "2022-01-04",
                "status": "paid",
                "barcode": {
                    "type": "code128",
                    "barcode": "86663260686492",
                    "status": "available",
                    "scanLimit": "once",
                    "scanLimitTimes": 1,
                    "redeemed": null
                },
                "discounts": [{
                    "code": "54647232687379",
                    "type": "InHouseBarcode",
                    "name": "reservation",
                    "amount": "0.00",
                    "externalId": null
                }],
                "externalIds": {
                    "account": {},
                    "product": {}
                },
                "options": [
                    {
                        "name": "First row parking",
                        "numberOfItems": 1,
                        "price": "0.00",
                        "priceInclTax": "0.00",
                        "priceExclTax": "0.00",
                        "taxes": [
                            {
                                "priceProportionPercentage": "100.00",
                                "taxAmount": "0",
                                "taxPercentage": "19.00",
                                "type": "VAT",
                                "taxableAmount": "0.00"
                            }
                        ]
                    }
                ],
                "refundDetails": {
                    "itemName": "Parking Ticket",
                    "itemPriceInclTax": "5.00",
                    "itemUuid": "3523249e-bc00-4e58-b1b0-31220531bc60",
                    "orderNumber": "95802491",
                    "conviousRefundFee": null,
                    "partnerRefundFee": 0.0,
                    "refundReason": "bad weather",
                    "refundedBy": "123@ticketoo.nl",
                    "eventDate": "2022-01-04",
                    "paymentDate": "2021-12-31T23:01:32.324472Z",
                    "refundedAt": "2022-01-05T08:48:22.346553Z",
                    "refundFeeType": "absolute"
                },
                "taxes": [{
                    "priceProportionPercentage": "100.00",
                    "taxAmount": "0.83",
                    "taxPercentage": "20.00",
                    "type": "VAT",
                    "taxableAmount": "5.00"
                }]
            }
        ],
        "discounts": [{
          "code": "54647232687379",
          "type": "InHouseBarcode",
          "name": "reservation",
          "amount": "0.00",
          "externalId": null
        }],
        "location": {
            "id": "d70aed5a-3960-44fa-9c08-f725c2b03ce8",
            "name": "Amsterdam"
        },
        "reseller": {
            "id": null,
            "name": null
        },
        "payments": [
            {
                "id": 6351596,
                "paymentProvider": "Mollie",
                "paymentMethod": "creditcard",
                "paymentStatus": "paid",
                "paymentDate": "2021-12-31T23:01:29.820951 | 00:00"
            }
        ]
    }]
}

Field	Type	Description
`next`	url	Url used to retrieve the next page of results. Null if this is the last page.
`previous`	url	Url used to retrieve the previous page of results. Null if this is the first page.
`results`	Order	List of orders in this page. See section "Order type" for details of the structure of payload.

Getting order information

Use case

This endpoint can be used to retrieve information about a single order.

HTTP Request

GET https://api.convious.com/api/v1/orders/<order_id>/?include=<inclusions>

Query Parameters

Parameter	Required	Description
`include`	No	Comma separated list of related entities included in the order. Possible inclusions:
		- `items` - includes tickets in the order
		- `items.barcode` - includes barcode information for each ticket. If supplied, also includes `items`
		- `items.external_ids` - includes all external ids associated with each ticket. If supplied, also includes `items`
		- `items.options` - includes options information of each order
		- `items.refund_details` - includes detailed refund information of each order
		- `items.taxes` - includes taxes information of each order
		- `customer` - includes customer information of the order
		- `discounts` - includes discount codes used in the order
		- `location` - includes location information of the order
		- `reseller` - includes reseller information of the order
		- `payments` - includes payment information of the order

Example output

Output received depends on include query parameter. The exact structure of it is defined in section "Order type". This documentation provides an example payload of a response with every entity included.

{
  "id": "f262d704-a7a0-45b3-af0f-920b3de9ec5a",
  "number": "95802491",
  "account": "convious_demo",
  "status": "confirmed",
  "productType": "tickets",
  "categoryId": "ce68fff6-4ce9-4996-b5d1-1020baf7d0ad",
  "orderDate": "2021-12-31T23:01:10.647104 | 00:00",
  "updatedAt": "2022-01-03T06:22:41.040608 | 00:00",
  "visitDate": "2022-01-04",
  "visitTime": "13:00:00",
  "visitEndTime": "14:00:00",
  "timezone": "Europe/Amsterdam",
  "ticketDownloadUrl": "https://api.convious-app.com/api/v1/cart/order/download/4976476/f262d704-a7a0-45b3-af0f-920b3de9ec5a/",
  "quantity": 4,
  "total": "49.20",
  "totalPriceInclTax": "49.20",
  "totalAfterDiscount": "49.20",
  "totalDiscountedPriceInclTax": "49.20",
  "totalDiscountedPriceExclTax": "48.37",
  "discountAmount": "0",
  "currency": "EUR",
  "locationId": "d70aed5a-3960-44fa-9c08-f725c2b03ce8",
  "emailStatus": "opened",
  "unfilledApf": false,
  "unfilledApfUrl": null,
  "printed": null,
  "downloaded": null,
  "externalId": null,
  "orderSource": "api",
  "madeBy": "",
  "customer": {
    "email": "demo | syfdg@ticketoo.nl",
    "language": "EN",
    "marketingOptIn": false
  },
  "items": [
    {
      "id": "f06afed5-a5ac-4fac-95e9-ce05c3089b46",
      "orderItemId": "3523249e-bc00-4e58-b1b0-31220531bc60",
      "productId": "0bda54d3-072e-425a-8d07-584515eb2fe7",
      "product": "Parking Ticket",
      "gatePrice": "6.00",
      "gatePriceInclTax": "6.00",
      "gatePriceExclTax": "",
      "pricePerItem": "5.00",
      "priceInclTax": "5.00",
      "priceExclTax": "4.17",
      "pricePerItemAfterDiscount": "5.00",
      "discountedPriceInclTax": "5.00",
      "discountedPriceExclTax": "4.17",
      "pricePerItemWithoutOptionsAfterDiscount": "5.00",
      "discountedPriceWithoutOptionsInclTax": "5.00",
      "discountedPriceWithoutOptionsExclTax": "4.17",
      "invalidatedAt": null,
      "validFrom": "2022-01-04T00:00:00 | 00:00",
      "validTo": "2022-01-04T23:59:59.999999 | 00:00",
      "refunded": false,
      "canRefund": true,
      "isBundle": false,
      "afterPaymentForm": {
        "name": "Lynda Hegmann III",
        "phone": "430730457"
      },
      "printed": "2022-01-04",
      "downloaded": "2022-01-04",
      "status": "paid",
      "barcode": {
        "type": "code128",
        "barcode": "86663260686492",
        "status": "available",
        "scanLimit": "once",
        "scanLimitTimes": 1,
        "redeemed": null
      },
      "discounts": [{
        "code": "54647232687379",
        "type": "InHouseBarcode",
        "name": "reservation",
        "amount": "0.00",
        "externalId": null
      }],
      "externalIds": {
        "account": {},
        "product": {}
      },
        "options": [
          {
            "name": "First row parking",
            "numberOfItems": 1,
            "price": "0.00",
            "priceInclTax": "0.00",
            "priceExclTax": "0.00",
            "taxes": [
              {
                "priceProportionPercentage": "100.00",
                "taxAmount": "0",
                "taxPercentage": "19.00",
                "type": "VAT",
                "taxableAmount": "0.00"
              }
            ]
          }
        ],
      "refundDetails": {
        "itemName": "Parking Ticket",
        "itemPriceInclTax": "5.00",
        "itemUuid": "3523249e-bc00-4e58-b1b0-31220531bc60",
        "orderNumber": "95802491",
        "conviousRefundFee": null,
        "partnerRefundFee": 0.0,
        "refundReason": "bad weather",
        "refundedBy": "123@ticketoo.nl",
        "eventDate": "2022-01-04",
        "paymentDate": "2021-12-31T23:01:32.324472Z",
        "refundedAt": "2022-01-05T08:48:22.346553Z",
        "refundFeeType": "absolute"
      },
      "taxes": [
        {
          "priceProportionPercentage": "100.00",
          "taxAmount": "0.83",
          "taxPercentage": "20.00",
          "type": "VAT",
          "taxableAmount": "5.00"
        }
      ]
    }
  ],
  "discounts": [{
    "code": "54647232687379",
    "type": "InHouseBarcode",
    "name": "reservation",
    "amount": "0.00",
    "externalId": null
  }],
  "location": {
    "id": "d70aed5a-3960-44fa-9c08-f725c2b03ce8",
    "name": "Amsterdam"
  },
  "reseller": {
    "id": null,
    "name": null
  },
  "payments": [
    {
      "id": 6351596,
      "paymentProvider": "Mollie",
      "paymentMethod": "creditcard",
      "paymentStatus": "paid",
      "paymentDate": "2021-12-31T23:01:29.820951 | 00:00"
    }
  ]
}

Creating a cart

Use case

This endpoint is used to create a cart of products that may be later converted into an order. Upon cart creation, the tickets are reserved for this cart and therefore are removed from available inventory for a limited time.

HTTP Request

POST https://api.convious.com/api/v1/accounts/<account_slug>/carts/

Request Payload

{
  "categoryId": "e8b6e763-91ee-40f9-863a-c91161c7747b",
  "eventDate": "2022-09-04",
  "startTime": "14:15:00",
  "endTime": "14:45:00",
  "externalId": "ba50f509",
  "items": [
    {
      "productId": "d9bdfb62-9f05-448b-9982-c27eb7449cb2",
      "amount": 2
    }
  ],
  "extras": {
    "key": "value"
  },
  "pricingToken": "eyJkdCI6ICIyMDIzLTEwLTEyIiwgInN0YXJ0X3RpbWUiOiAiMDk6MDA6MDAiLCA"
}

Field	Type	Description
`categoryId`	UUID	Id of the category for the cart. This field is not mandatory for backwards compatibility reasons, but it is strongly advised to send a category Id when creating a cart
`eventDate`	date	Date for the tickets of the cart. Null if tickets are undated
`startTime`	time	Start time of a timeslot on event date for the tickets of the cart. Null if tickets are undated or if it is a full day event
`endTime`	time	End time of a timeslot on event date for the tickets of the cart. Null if tickets are undated, if it is a full day event or if the timeslot has no end time
`externalId`	string	An id for this cart in the caller's system. This is used for bookkeeping purposes. If the cart results in an order, the order will inherit its external id.
`items`	CartItem[]	The contents of the cart
`items.productId`	UUID	The id of the product in the cart
`items.amount`	number	The number of tickets of this product in the cart
`extras`	key-value pairs	Arbitrary key-value information saved to this cart. If the cart results in an order, it will inherit this information
`pricingToken`	string	A pricing token received from our pricing API. If not specified, all the items in the cart will have a price of 0, indicating that the order has no price. If specified, the pricing information from our pricing API will be used for this cart. The cart contents, event date and start/end times must match exactly with the token returned from our pricing API, else the operation will fail.

Response

Upon success a HTTP 200 OK response is returned with Location header containing the url to newly created cart.

Updating a cart

Use case

This endpoint is used to update products in a cart. Upon cart update, reservations and inventory of the cart is also updated.

HTTP Request

PATCH https://api.convious.com/api/v1/accounts/<account_slug>/carts/<cart_id>/

Request Payload

{
  "items": [
    {
      "productId": "d9bdfb62-9f05-448b-9982-c27eb7449cb2",
      "amount": 2
    }
  ],
  "pricingToken": "eyJkdCI6ICIyMDIzLTEwLTEyIiwgInN0YXJ0X3RpbWUiOiAiMDk6MDA6MDAiLCA"
}

Field	Type	Description
`items`	CartItem[]	The new contents of the cart
`pricingToken`	string	A pricing token received from our pricing API. If not specified, all the items in the cart will have a price of 0, indicating that the order has no price. If specified, the pricing information from our pricing API will be used for this cart. The cart contents, event date and start/end times must match exactly with the token returned from our pricing API, else the operation will fail.

Response

Upon success a HTTP 200 OK response is returned.

Getting a cart

Use case

This endpoint is used to retrieve cart information.

HTTP Request

GET https://api.convious.com/api/v1/accounts/<account_slug>/carts/<cart_id>/

Example output

{
  "id": "bdc8a051-3f69-4e5a-94c7-2416c77f979c",
  "categoryId": "e8b6e763-91ee-40f9-863a-c91161c7747b",
  "eventDate": "2022-09-04",
  "startTime": "14:15:00",
  "endTime": "14:45:00",
  "externalId": "ba50f509",
  "totalPrice": "39.98",
  "totalPriceAfterDiscount": "39.98",
  "items": [
    {
      "productId": "d9bdfb62-9f05-448b-9982-c27eb7449cb2",
      "amount": 2,
      "price": "19.99",
      "gatePrice": "25.00"
    }
  ],
  "extras": {
    "key": "value"
  },
  "priceIncludesTax": true,
  "expiresAt": "2022-08-05T15:24:33.123456+00:00",
  "referenceId": "12623-32800-12345",
  "createdAt": "2022-08-05T09:00:33.123456+00:00",
  "updatedAt": "2022-08-05T09:00:33.123456+00:00",
  "timezone": "Europe/Amsterdam",
  "status": "open"
}

Field	Type	Description
`id`	UUID	Id of the cart
`categoryId`	UUID	Id of the category for the cart
`eventDate`	date	Date for the tickets of the cart. Null if tickets are undated
`startTime`	time	Start time of a timeslot on event date for the tickets of the cart. Null if tickets are undated or if it is a full day event
`endTime`	time	End time of a timeslot on event date for the tickets of the cart. Null if tickets are undated, if it is a full day event or if the timeslot has no end time
`externalId`	string	An id for this cart in the caller's system. This is used for bookkeeping purposes. If the cart results in an order, the order will inherit its external id.
`total`	number as string	Total non discounted value of items in this cart. If the cart was created without pricing token, the price will be 0.
`totalAfterDiscount`	number as string	Total value of items in this cart after discount codes were applied. If the cart was created without pricing token, the price will be 0.
`items`	CartItem[]	The contents of the cart
`items.productId`	UUID	The id of the product in the cart
`items.amount`	number	The number of tickets of this product in the cart
`items.price`	number as string	The per-item price of the cart item. If the cart was created without pricing token, the price will be 0.
`items.gatePrice`	number as string	The price at which the product is sold at the gate of the venue.
`extras`	key-value pairs	Arbitrary key-value information saved to this cart. If the cart results in an order, it will inherit this information
`priceIncludesTax`	boolean	Indicates if the price includes tax
`expiresAt`	datetime	Timestamp until which the specified cart is valid (e.g. reservations on inventory are held). After this time, the cart might still be used to produce the order, but it may fail due to no availability left. If the value is null, the cart is valid indefinitely.
`referenceId`	string	Reference Id of the cart
`createdAt`	datetime	Timestamp at which the cart was created.
`updatedAt`	datetime	Timestamp at which the cart was last updated.
`timezone`	string	Timezone identifier of the venue for which the cart is for.
`status`	string	The status of the cart.

Deleting a cart

Use case

This endpoint is used to remove the cart and free up all associated inventory reservations.

HTTP Request

DELETE https://api.convious.com/api/v1/accounts/<account_slug>/carts/<cart_id>/

Response

Upon success a HTTP 200 OK response is returned.

Making a booking

Use case

This endpoint is used to convert a given cart into a paid order. The payment is assumed to be handled outside Convious.

HTTP Request

POST https://api.convious.com/api/v1/accounts/<account_slug>/bookings/

Request payload

{
  "cartId": "e0fc70c0-67ec-4ee5-9408-aefd5ec3a499",
  "customer": {
    "email": "john.doe@gmail.com",
    "name": "John",
    "language": "en"
  },
  "extras": {
    "key": "value"
  },
  "source": "api"
}

Field	Type	Description
`cartId`	UUID	The id of the cart to make a booking for.
`customer`	Customer	Customer information that the order should be for. If not set, customer of the cart (if any) will be used.
`customer.email`	string	The email of the customer.
`customer.name`	string	The name of the customer.
`customer.language`	string	The preferred language of the customer.
`extras`	key-value pairs	Arbitrary key-value information saved to the order. It is merged with the extras field of the cart.
`source`	string	DEPRECATED. The sales channel that the order originated from. If not specified by us otherwise, either omit it or set it to "api"

Response

Upon success a HTTP 200 OK response is returned with Location header containing the url to newly created order.

Cancelling an order

Use case

This endpoint is used to cancel an already made order. A full refund will be issued to all payments made (if any) for that order.

HTTP Request

POST https://api.convious.com/api/v1/orders/<order_id>/status/

Request payload

{
  "status": "cancelled",
  "statusReason": "Reason for the status"
}

Field	Type	Description
`status`	string	The desired status of the order. Currently only "cancelled" is accepted.
`statusReason`	string	The reason why the status is being changed.

Response

Upon success a HTTP 200 OK response is returned.

Products API

Product Type

Several endpoints make use of this type in their responses. The actual data returned depends on what include options were selected (see documentation of endpoints themselves for more details). This documentation provides an example of how a product payload looks like with everything included.

{
    "id": "4bf03611-f448-4fe8-ab6c-dd2c55a59c6a",
    "accountSlug": "convious_demo",
    "priority": 1,
    "minTickets": 1,
    "maxTickets": 10,
    "showFrom": "2020-04-29",
    "showTo": "2025-01-01",
    "validFrom": "2020-08-01",
    "validTo": "2025-01-01",
    "ticketDuration": null,
    "ticketTimeDuration": null,
    "isBundle": false,
    "enabled": true,
    "apfEnabled": true,
    "name": {
        "en": "Adult ticket 18+",
        "nl": "Volwassen ticket 18+"
    },
    "account": {
        "slug": "convious_demo",
        "name": "Convious Marketing | Demo Check-Out"
    },
    "text": {
        "description": {
            "en": "From 18 until 65 years old. Visit any time!",
            "nl": "Van 18-65 jaar."
        }
    },
    "categories": [
        {
            "id": "ce68fff6-4ce9-4996-b5d1-1020baf7d0ad",
            "flow": "rtp"
        }
    ],
    "inactiveCategories": [
        {
            "id": "e2e6c498-4ce9-4d13-b5d1-1020baf7d0ad",
            "flow": "rtp"
        }
    ],
    "resources": [
        {
            "inventoryPoolId": "e2e6c498-eb92-4d13-95ad-0e5daa3aa10f",
            "categoryId": null,
            "amountUsed": 1
        }
    ],
    "images": [
        {
            "rel": "default",
            "url": "https://images.convious.com/uploads/e2096755-e5a1-4a90-95f1-aca08ab80115.jpeg"
        }
    ],
    "externalIds": {
        "Countr": "87487787df2443"
    },
    "barcode": {
        "format": "code128"
    },
    "taxes": [
        {
            "type": "VAT",
            "priceProportionPercentage": "100.00",
            "taxPercentage": "20.00"
        }
    ],
    "scanOptions": {
        "scanLimit": "once",
        "scanLimitType": "scan_period_fixed",
        "maxScans": 10,
        "maxScansPerDay": 10
    }
}

Fields

Field	Type	Description
`id`	UUID	An id of the product
`accountSlug`	string	An account slug of the account of the product
`priority`	string	Priority of the product. Lower number means higher priority.
`minTickets`	number	Minimum number of tickets in an order
`maxTickets`	number	Maximum number of tickets in an order
`showFrom`	date	Date from which the product is shown in the checkout
`showTo`	date	Date until which the product is shown in the checkout
`validFrom`	date	Date from which the product is available to be used (for dated tickets this represents possible dates to be selected in the calendar)
`validTo`	date	Date until which the product is available to be used (for dated tickets this represents possible dates to be selected in the calendar)
`ticketDuration`	string	ISO8601 duration representing how long the ticket is valid for once bought. If missing, the ticket is valid until scanned.
`ticketTimeDuration`	string	ISO8601 duration representing how long the ticket is valid for once scanned. This is used for pay-per-minute overtime calculations
`isBundle`	boolean	Indicates if the product is a bundle
`enabled`	boolean	Indicates if the product is enabled. Disabled products should not normally be sold.
`apfEnabled`	boolean	Indicates if the after payment form (APF) is enabled for product.
`businessType`	string	Indicates article (product) business type, used for generating various reports.
`pricingType`	string	Indicates how the article should be priced.
`createdAt`	datetime	Timestamp at which the product was created.
`updatedAt`	datetime	Timestamp at which the product was last updated.
`name`	key-value pairs	Name of the product in various languages. Only part of the payload if name is added to inclusions.
`account`	Account	Account of this product. Only part of the payload if account is added to inclusions.
`account.slug`	string	An account slug of the account of the product
`account.name`	string	An account name of the account of the product
`text`	Text	Text information about this product. Only part of the payload if text is added to inclusions.
`text.description`	key-value pairs	Description of the product in various languages
`categories`	Category[]	Categories assigned to this product. Only part of the payload if categories is added to inclusions.
`categories.id`	UUID	Category id
`categories.flow`	string	Checkout flow of this category. Possible values: undated, dated, rtp, date_change, date_reservation
`inactiveCategories`	Category[]	Inactive categories assigned to this product. Inactive category is a category that was disabled itself or has disabled parents.
`inactiveCategories.id`	UUID	Inactive category id
`inactiveCategories.flow`	string	Checkout flow of this inactive category. Possible values: undated, dated, rtp, date_change, date_reservation
`resources`	Resource[]	Resources used by this product. Only part of the payload if resources is added to inclusions.
`resources.inventoryPoolId`	UUID	The id of inventory pool used.
`resources.categoryId`	UUID	Category id to which the resource usage is applicable. If null, it is applicable for every category.
`resources.amountUsed`	number	Amount used from the inventory pool per single ticket.
`images`	Image[]	Images related to this product. Only part of the payload if images is added to inclusions.
`images.rel`	string	The type of the image for the product
`images.url`	string	The url of the image
`externalIds`	key-value pairs	External ids of the product per integration type. Only part of the payload if external ids is added to inclusions.
`barcode`	Barcode	Barcode information of the tickets for this product. Only part of the payload if barcode is added to inclusions.
`tax.type`	string	Type of this tax. Possible value: VAT.
`tax.priceProportionPercentage`	decimal	Percentage of product price this tax should be applied on.
`tax.taxPercentage`	decimal	Tax rate.
`scanOptions.scanLimit`	string	Barcode scan limit.
`scanOptions.scanLimitType`	string	The type of scan.
`scanOptions.maxScans`	integer	Maximum number of scans available for this type of ticket.
`scanOptions.maxScansPerDay`	integer	Maximum scans allowed per day.

Listing products

Use case

This endpoint can be used to list all products that exist in Convious system

HTTP Request

GET https://api.convious.com/api/v1/products/?account=<account_slug>&category_id=<category_id>&has_external_id=<has_external_id>&include=<inclusions>&enabled=<enabled>

Query Parameters

Parameter	Required	Description
`account`	Permission dependent	Account slug to retrieve products for. Required in most cases, if omitted, returns products of every account.
`category_id`	No	Category id that the products must be part of. Returns all products regardless of category if omitted.
`has_external_id`	No	Used to filter returned products that have an external id of specific integration. The value of the parameter is the integration type that the caller is interested in.
`include`	No	Comma separated list of related entities included in the product. Possible inclusions:
		- `name` - includes product translated names
		- `account` - includes product account information
		- `text` - includes texts related to the product
		- `categories` - includes categories that the product is part of
		- `resources` - includes resources used by this product
		- `images` - includes images related to this product
		- `external_ids` - includes external ids of this product
		- `barcode` - includes barcode information of this product
		- `taxes` - includes tax information of this product
		- `scan_options` - includes scan options related to this product
`enabled`	No	Set to `true` to only receive enabled products, `false` to only receive disabled ones. Do not set to receive all products.

Example output

Output received depends on include query parameter. This documentation provides an example payload of a response with every entity included.

{
    "next": "https://api.convious.com/api/v1/products/?account=convious_demo&cursor=cD02Njcx",
    "previous": null,
    "results": [
        {
            "id": "4bf03611-f448-4fe8-ab6c-dd2c55a59c6a",
            "accountSlug": "convious_demo",
            "priority": 1,
            "minTickets": 1,
            "maxTickets": 10,
            "showFrom": "2020-04-29",
            "showTo": "2025-01-01",
            "validFrom": "2020-08-01",
            "validTo": "2025-01-01",
            "ticketDuration": null,
            "ticketTimeDuration": null,
            "isBundle": false,
            "enabled": true,
            "apfEnabled": true,
            "businessType": "single_visit_ticket",
            "pricingType": "upsell",
            "createdAt": "2006-01-02T15:04:05.999Z",
            "updatedAt": "2006-01-02T15:04:05.999Z",
            "name": {
                "en": "Adult ticket 18+",
                "nl": "Volwassen ticket 18+"
            },
            "account": {
                "slug": "convious_demo",
                "name": "Convious Marketing | Demo Check-Out"
            },
            "text": {
                "description": {
                    "en": "From 18 until 65 years old. Visit any time!",
                    "nl": "Van 18-65 jaar."
                }
            },
            "categories": [
                {
                    "id": "ce68fff6-4ce9-4996-b5d1-1020baf7d0ad",
                    "flow": "rtp"
                }
            ],
            "inactiveCategories": [
                {
                    "id": "e2e6c498-4ce9-4d13-b5d1-1020baf7d0ad",
                    "flow": "rtp"
                }
            ],
            "resources": [
                {
                    "inventoryPoolId": "e2e6c498-eb92-4d13-95ad-0e5daa3aa10f",
                    "categoryId": null,
                    "amountUsed": 1
                }
            ],
            "images": [
                {
                    "rel": "default",
                    "url": "https://images.convious.com/uploads/e2096755-e5a1-4a90-95f1-aca08ab80115.jpeg"
                }
            ],
            "externalIds": {
                "Countr": "87487787df2443"
            },
            "barcode": {
                "format": "code128"
            },
            "taxes": [
                {
                    "type": "VAT",
                    "priceProportionPercentage": "100.00",
                    "taxPercentage": "20.00"
                }
            ],
            "scanOptions": {
                "scanLimit": "once",
                "scanLimitType": "scan_period_fixed",
                "maxScans": 10,
                "maxScansPerDay": 10
            }
        }
    ]
}

Field	Type	Description
`next`	url	Url used to retrieve the next page of results. Null if this is the last page.
`previous`	url	Url used to retrieve the previous page of results. Null if this is the first page.
`results`	Order	List of product in this page. See section "Product type" for details of the structure of payload.

Getting product information

Use case

This endpoint can be used to retrieve information about a single product.

HTTP Request

GET https://api.convious.com/api/v1/products/<product_id>/?include=<inclusions>

Query Parameters

Parameter	Required	Description
`include`	No	Comma separated list of related entities included in the product. Possible inclusions:
		- `name` - includes product translated names
		- `account` - includes product account information
		- `text` - includes texts related to the product
		- `categories` - includes categories that the product is part of
		- `resources` - includes resources used by this product
		- `images` - includes images related to this product
		- `external_ids` - includes external ids of this product
		- `barcode` - includes barcode information of this product
		- `taxes` - includes tax information of this product
		- `scan_options` - includes scan options related to this product

Example output

Output received depends on include query parameter. The exact structure of it is defined in section "Product type". This documentation provides an example payload of a response with every entity included.

{
    "id": "4bf03611-f448-4fe8-ab6c-dd2c55a59c6a",
    "accountSlug": "convious_demo",
    "priority": 1,
    "minTickets": 1,
    "maxTickets": 10,
    "showFrom": "2020-04-29",
    "showTo": "2025-01-01",
    "validFrom": "2020-08-01",
    "validTo": "2025-01-01",
    "ticketDuration": null,
    "ticketTimeDuration": null,
    "isBundle": false,
    "enabled": true,
    "apfEnabled": true,
    "businessType": "single_visit_ticket",
    "pricingType": "upsell",
    "createdAt": "2006-01-02T15:04:05.999Z",
    "updatedAt": "2006-01-02T15:04:05.999Z",
    "name": {
        "en": "Adult ticket 18+",
        "nl": "Volwassen ticket 18+"
    },
    "account": {
        "slug": "convious_demo",
        "name": "Convious Marketing | Demo Check-Out"
    },
    "text": {
        "description": {
            "en": "From 18 until 65 years old. Visit any time!",
            "nl": "Van 18-65 jaar."
        }
    },
    "categories": [
        {
            "id": "ce68fff6-4ce9-4996-b5d1-1020baf7d0ad",
            "flow": "rtp"
        }
    ],
    "inactiveCategories": [
        {
            "id": "e2e6c498-4ce9-4d13-b5d1-1020baf7d0ad",
            "flow": "rtp"
        }
    ],
    "resources": [
        {
            "inventoryPoolId": "e2e6c498-eb92-4d13-95ad-0e5daa3aa10f",
            "categoryId": null,
            "amountUsed": 1
        }
    ],
    "images": [
        {
            "rel": "default",
            "url": "https://images.convious.com/uploads/e2096755-e5a1-4a90-95f1-aca08ab80115.jpeg"
        }
    ],
    "externalIds": {
        "Countr": "87487787df2443"
    },
    "barcode": {
        "format": "code128"
    },
    "taxes": [
        {
            "type": "VAT",
            "priceProportionPercentage": "100.00",
            "taxPercentage": "20.00"
        }
    ],
    "scanOptions": {
        "scanLimit": "once",
        "scanLimitType": "scan_period_fixed",
        "maxScans": 10,
        "maxScansPerDay": 10
    }
}

Getting product availability

Use case

This endpoint can be used to retrieve availability of a single product for a period of time.

HTTP Request

GET https://api.convious.com/api/v1/products/<product_id>/availability/?date_from=<date_from>&date_to=<date_to>&category_id=<category_id>

Query Parameters

Parameter	Required	Description
`date_from`	Yes	Date from which the availability should be returned
`date_to`	Yes	Date until which the availability should be returned. This date is exclusive, e.g. results will include up to but not including this day.
`category_id`	No	Category id that should be used for availability. If not provided, the first category that the product is assigned to will be used.

Example output

{
    "results": [
        {
            "productId": "4bf03611-f448-4fe8-ab6c-dd2c55a59c6a",
            "categoryId": "ce68fff6-4ce9-4996-b5d1-1020baf7d0ad",
            "day": "2022-08-01",
            "timeFrom": "09:00:00",
            "timeFromOffset": "+02:00",
            "timeTo": "10:00:00",
            "timeToOffset": "+02:00",
            "availability": 100
        }
    ]
}

Field	Type	Description
`results.productId`	UUID	Id of the product
`results.categoryId`	UUID	Id of the category to which this availability is applicable to.
`results.day`	date	The day of availability
`results.timeFrom`	time	The starting time of a timeslot period in venue's time. Null if the venue has no timeslots.
`results.timeFromOffset`	string	The timezone offset of starting time
`results.timeTo`	time	The ending time of a timeslot period in venue's time. Null if the venue has no timeslots or if the timeslots only have starting time.
`results.timeToOffset`	string	The timezone offset of ending time
`results.availability`	number	The amount of available tickets for this timeslot. Null means unlimited availability.

Getting available days for a cart of products

Use case

This endpoint can be used to display a calendar of available days given a set of products and their amounts.

HTTP Request

POST https://api.convious.com/api/v1/accounts/<account_slug>/availability/for_period/<date_from>/<date_to>/

URL Parameters

Parameter	Required	Description
`account_slug`	Yes	Account slug to retrieve the availability for.
`date_from`	Yes	Date from which the availability should be returned.
`date_to`	Yes	Date until which the availability should be returned. This date is exclusive, e.g. results will include up to but not including this day. The period between this date and `date_to` should not exceed 60 days.

Request payload

{
  "categoryId": "e0fc70c0-67ec-4ee5-9408-aefd5ec3a499",
  "products": [
    {
        "id": "e8139c8e-0025-417d-81db-981707b2efc4",
        "amount": 1
    },
    ...
  ]
}

Field	Type	Description
`categoryId`	UUID	The id of the category to get the availability for. Influences which timeslots (if any) are used, when the venue is closed, etc. If null or omitted, these settings are taken from account level. Should be specified if the account is using categories.
`products`	CartItem[]	The contents of the cart
`products.id`	UUID	The id of the product in the cart
`products.amount`	number	The number of tickets of this product in the cart

Example output

{
    "results": [
        {
            "day": "2022-08-01",
            "available": true
        }
    ]
}

Field	Type	Description
`results.day`	date	The day of availability
`results.available`	boolean	Whether the specified products in the request are available on that day.

Getting available times for a cart of products on a day

Use case

This endpoint can be used to get available timeslots given a day, a set of products and their amounts.

HTTP Request

POST https://api.convious.com/api/v1/accounts/<account_slug>/availability/<date>/

URL Parameters

Parameter	Required	Description
`account_slug`	Yes	Account slug to retrieve the availability for.
`date`	Yes	Date for which the availability should be returned.

Request payload

{
  "categoryId": "e0fc70c0-67ec-4ee5-9408-aefd5ec3a499",
  "products": [
    {
        "id": "e8139c8e-0025-417d-81db-981707b2efc4",
        "amount": 1
    },
    ...
  ]
}

Field	Type	Description
`categoryId`	UUID	The id of the category to get the availability for. Influences which timeslots (if any) are used, when the venue is closed, etc. If null or omitted, these settings are taken from account level. Should be specified if the account is using categories.
`products`	CartItem[]	The contents of the cart
`products.id`	UUID	The id of the product in the cart
`products.amount`	number	The number of tickets of this product in the cart

Example output

{
    "results": [
        {
            "day": "2022-08-01",
            "timeFrom": "09:00:00",
            "timeFromOffset": "+02:00",
            "timeTo": "10:00:00",
            "timeToOffset": "+02:00",
            "available": true
        }
    ]
}

Field	Type	Description
`results.day`	date	The day of availability
`results.timeFrom`	time	The starting time of a timeslot period in venue's time. Null if the venue has no timeslots.
`results.timeFromOffset`	string	The timezone offset of starting time
`results.timeTo`	time	The ending time of a timeslot period in venue's time. Null if the venue has no timeslots or if the timeslots only have starting time.
`results.timeToOffset`	string	The timezone offset of ending time
`results.available`	boolean	Whether the products specified in the request are available at this timeslot.

Categories API

Listing categories

Use case

This endpoint can be used to list all categories that exist in Convious system

HTTP Request

GET https://api.convious.com/api/v1/categories/?account=<account_slug>&include=<inclusions>

Query Parameters

Parameter	Required	Description
`account`	Permission dependent	Account slug to retrieve categories for. Required in most cases, if omitted, returns products of every account.
`parent_category`	No	Used to filter returned categories by parent category `UUID`. If omitted, returns categories regardless of parent.
`root`	No	Used to filter returned only root categories i.e. categories without parent. If omitted, returns categories regardless of parent. Accepted values are: `true`, `false`.
`include`	No	Comma separated list of related entities included in the category. Possible inclusions:
		- `name` - includes category translated names
		- `parent_category` - includes parent category information
		- `images` - includes images related to this category
		- `text` - includes texts related to the category

Example output

Output received depends on include query parameter. This documentation provides an example payload of a response with every entity included.

{
    "next": "https://api.convious.com/api/v1/categories/?account=convious_demo&cursor=cD0xNzI5&include=name%2Cparent_category",
    "previous": null,
    "results": [
        {
            "id": "ce68fff6-4ce9-4996-b5d1-1020baf7d0ad",
            "accountSlug": "convious_demo",
            "priority": 1,
            "enabled": true,
            "showedInCheckout": true,
            "name": {
                "en": "Dated Tickets",
                "de": "Kaart op datum"
            },
            "text": {
                "description": {
                    "en": "Book your timeslot with your membership card!",
                    "nl": "Reserveer hier uw tijdslot."
                }
            },
            "parentCategory": {
                "id": "ab66edd3-4017-4fac-a688-e2896235ba3a"
            },
            "images": [
                {
                    "rel": "default",
                    "url": "https://images.convious.com/uploads/e2096755-e5a1-4a90-95f1-aca08ab80115.jpeg"
                },
                {
                    "rel": "square",
                    "url": "https://images.convious.com/uploads/e2096755-e2a1-4a90-95f1-asd08ab80226.jpeg"
                }
            ]
        }
    ]
}

Field	Type	Description
`next`	url	Url used to retrieve the next page of results. Null if this is the last page.
`previous`	url	Url used to retrieve the previous page of results. Null if this is the first page.
`results`	Order	List of categories in this page.
`id`	UUID	Id of the category.
`accountSlug`	string	An account slug of the account of the category.
`priority`	integer	Priority of the category. Lower number means higher priority.
`enabled`	boolean	Marks if category is enabled.
`showedInCheckout`	integer	Marks if category is displayed in Convious checkout.
`name`	key-value pairs	Name of the category in various languages.
`parentCategory.id`	UUID	Id of parent category. `null` if category has no parent.
`images`	Image[]	Images related to this category. Only part of the payload if images is added to inclusions.
`images.rel`	string	The type of the image for the product
`images.url`	string	The url of the image
`text`	Text	Text information about this category. Only part of the payload if text is added to inclusions.
`text.description`	key-value pairs	Description of the category in various languages

Pricing API

Getting daily prices of a cart

Use case

This endpoint could be used to display a calendar with pricing information given a cart of products. One price per day will be returned, representing the cheapest timeslot (if any) on that day.

HTTP Request

POST https://api.convious.com/api/v1/accounts/<account_slug>/pricing/for_period/<date_from>/<date_to>/

URL Parameters

Parameter	Required	Description
`account_slug`	Yes	Account slug to retrieve the pricing for.
`date_from`	Yes	Date from which the pricing should be returned.
`date_to`	Yes	Date until which the pricing should be returned. This date is exclusive, e.g. results will include up to but not including this day. The period between this date and `date_to` should not exceed 60 days.

Request payload

{
  "categoryId": "e0fc70c0-67ec-4ee5-9408-aefd5ec3a499",
  "products": [
    {
        "id": "e8139c8e-0025-417d-81db-981707b2efc4",
        "amount": 1
    },
    ...
  ]
}

Field	Type	Description
`categoryId`	UUID	The id of the category to get the prices for. Influences which timeslots (if any) are used, when the venue is closed, etc. If null or omitted, these settings are taken from account level. Should be specified if the account is using categories.
`products`	CartItem[]	The contents of the cart
`products.id`	UUID	The id of the product in the cart
`products.amount`	number	The number of tickets of this product in the cart

Example output

{
    "prices": [
        {
            "day": "2023-02-01",
            "available": true,
            "price": "6.50",
            "originalPrice": "15.00",
            "color": 4,
            "colorCode": "#00AC1E"
        }
    ]
}

Field	Type	Description
`prices`	CalendarPrice	A list of pricing information for each calendar day requested.
`prices.day`	date	Calendar day for which the pricing information is for
`prices.available`	boolean	Whether or not there are tickets available on that day (e.g. if there is enough inventory, if the venue is not closed etc.)
`prices.price`	decimal	The price for the cart on that day.
`prices.originalPrice`	decimal	The original price for the cart (e.g. if buying it at the gate)
`prices.color`	integer	The price color as integer.
`prices.colorCode`	string	The price color as hex code.

Getting timeslot prices of a cart

Use case

This endpoint could be used to display timeslots with pricing information given a cart of products. One price per timeslot will be returned.

HTTP Request

POST https://api.convious.com/api/v1/accounts/<account_slug>/pricing/<date>/

URL Parameters

Parameter	Required	Description
`account_slug`	Yes	Account slug to retrieve the pricing for.
`date`	Yes	Date for which the pricing should be returned.

Request payload

{
  "categoryId": "e0fc70c0-67ec-4ee5-9408-aefd5ec3a499",
  "products": [
    {
        "id": "e8139c8e-0025-417d-81db-981707b2efc4",
        "amount": 1
    },
    ...
  ]
}

Field	Type	Description
`categoryId`	UUID	The id of the category to get the prices for. Influences which timeslots (if any) are used, when the venue is closed, etc. If null or omitted, these settings are taken from account level. Should be specified if the account is using categories.
`products`	CartItem[]	The contents of the cart
`products.id`	UUID	The id of the product in the cart
`products.amount`	number	The number of tickets of this product in the cart

Example output

{
    "prices": [
        {
            "day": "2023-02-01",
            "timeFrom": "09:00:00",
            "timeFromOffset": "+02:00",
            "timeTo": "10:00:00",
            "timeToOffset": "+02:00",
            "available": true,
            "price": "6.50",
            "originalPrice": "15.00",
            "pricingToken": "eyJkdCI6ICIyMDIzLTEwLTEyIiwgInN0YXJ0X3RpbWUiOiAiMDk6MDA6MDAiLCA",
            "color": 4,
            "colorCode": "#00AC1E"
        }
    ]
}

Field	Type	Description
`prices`	CalendarPrice	A list of pricing information for each timeslot requested.
`prices.day`	date	Calendar day for which the pricing information is for
`prices.timeFrom`	time	The starting time of a timeslot period in venue's time. Null if the venue has no timeslots.
`prices.timeFromOffset`	string	The timezone offset of starting time
`prices.timeTo`	time	The ending time of a timeslot period in venue's time. Null if the venue has no timeslots or if the timeslots only have starting time.
`prices.timeToOffset`	string	The timezone offset of ending time
`prices.available`	boolean	Whether or not there are tickets available on that timeslot (e.g. if there is enough inventory, if the venue is not closed etc.)
`prices.price`	decimal	The price for the cart on that timeslot.
`prices.originalPrice`	decimal	The original price for the cart (e.g. if buying it at the gate)
`prices.pricingToken`	string	A token that can be used to set prices when creating or updating the cart. See Creating a cart for more information.
`prices.color`	integer	The price color as integer.
`prices.colorCode`	string	The price color as hex code.

Scanning API

Scan Result Type

{
    "status": "success",
    "reason": "Barcode 8972467863 is Valid",
    "errorCode": null,
    "overtimeSeconds": 0,
    "remainingSeconds": null,
    "product": {
        "id": "ab37120c-d67b-4b6d-a5d8-f5c9264375c3",
        "name": {
            "en": "Adult day ticket",
            "de": "Tageskarte für Erwachsene"
        }
    },
    "order": {
        "eventDate": "2023-03-04",
        "startTime": "10:00:00",
        "endTime": "11:00:00",
    },
    "ticket": {
        "validFrom": "2023-03-04T00:00:00+01:00",
        "validTo": "2023-03-04 23:59:59.999999+01:00",
        "priceBeforeDiscount": "23.50",
        "price": "23.50",
        "extraInfo": {
            "buyerFirstName": "John",
            "buyerLastName": "Smith"
        },
    },
    "customer": {
        "email": "john.smith@acme.co",
        "language": "en"
    }
}

Field	Type	Description
`status`	string	Either "success" or "error", depending if the barcode is valid.
`reason`	string	A human readable reason why the barcode could or could not be redeemed.
`errorCode`	string	A machine-readable reason of why this barcode could not be redeemed. Possible values are:
		- `not_found` - The barcode does not exist or has not been sold yet
		- `already_redeemed` - The barcode has already been previously redeemed and has exceeded its redemption limit
		- `already_scanned_in` - The barcode has been "scanned in" and another attempt is being made to scan it with the direction "in"
		- `scan_in_required` - An attempt was made to scan this barcode with direction "out" without first scanning it in
		- `time_limit_reached` - An attempt was made to scan this barcode with direction "out" when the pay-per-minute ticket has accrued overtime and the venue does not allow overtime scans
		- `not_scannable_code` - The barcode is for a pay-later order that has not been paid yet
		- `future_validity` - The barcode is not valid yet, but is valid in the future
		- `past_validity` - The validity of the barcode is expired
`overtimeSeconds`	integer	In case of this barcode being for ticket that is pay-per-minute, the number of seconds that the ticket holder is over the paid time
`remainingSeconds`	integer	In case of this barcode being for ticket that is pay-per-minute, the number of seconds that remains of paid time
`product.id`	string	The id of the product
`product.name`	key-value-pairs	The translated names of the product
`order.eventDate`	date	The date of the event.
`order.startTime`	time	The start time of the event in venue's timezone. Generally `validFrom` and `validTo` should be used instead to check barcode validity, this time could be used for display purposes.
`order.endTime`	time	The end time of the event in venue's timezone. Generally `validFrom` and `validTo` should be used instead to check barcode validity, this time could be used for display purposes.
`ticket.validFrom`	datetime	Date/time in venue's timezone of when the validity of the barcode starts.
`ticket.validTo`	datetime	Date/time in venue's timezone of when the validity of the barcode ends.
`ticket.priceBeforeDiscount`	decimal	The price of the ticket for which the barcode is for before any discounts were applied.
`ticket.price`	decimal	The price the ticket holder ended up paying for the ticket for which the barcode is for.
`ticket.extraInfo`	key-value pairs	After payment form information that has been filled in for this specific ticket.
`customer.email`	string	The customer's email address.
`customer.language`	string	The language code of the language that the customer used to buy the ticket.

Checking if a barcode is valid

Use case

This endpoint can be used to verify if a barcode is valid at the time of the API call, without actually redeeming it.

HTTP Request

GET https://api.convious.com/api/v2/accounts/<account_slug>/barcode/scan/?barcode=<barcode>&scanned_at=<scanned_at>&direction=<direction>

URL Parameters

Parameter	Required	Description
`account_slug`	Yes	Account slug for which the scan is to be made.

Query Parameters

Parameter	Required	Description
`barcode`	Yes	The barcode to be scanned.
`scanned_at`	No	The desired date / time in ISO8601 format of when the scan should be happening. If not specified, the scan is assumed to take place at the time the API is called.
`direction`	No	Either "in" or "out". Used in case it is required to register the ticket holder both entering and leaving the venue. If not specified, the scanning behaves as if the ticket holder is attempting to enter the venue.

Example output

The exact structure of response payload is defined in section "Scan Result Type".

{
    "status": "success",
    "reason": "Barcode 8972467863 is Valid",
    "errorCode": null,
    "overtimeSeconds": 0,
    "remainingSeconds": null,
    "product": {
        "id": "ab37120c-d67b-4b6d-a5d8-f5c9264375c3",
        "name": {
            "en": "Adult day ticket",
            "de": "Tageskarte für Erwachsene"
        }
    },
    "order": {
        "eventDate": "2023-03-04",
        "startTime": "10:00:00",
        "endTime": "11:00:00",
    },
    "ticket": {
        "validFrom": "2023-03-04T00:00:00+01:00",
        "validTo": "2023-03-04 23:59:59.999999+01:00",
        "priceBeforeDiscount": "23.50",
        "price": "23.50",
        "extraInfo": {
            "buyerFirstName": "John",
            "buyerLastName": "Smith"
        },
    },
    "customer": {
        "email": "john.smith@acme.co",
        "language": "en"
    }
}

Redeeming a barcode

Use case

This endpoint can be used to redeem a barcode.

HTTP Request

POST https://api.convious.com/api/v2/accounts/<account_slug>/barcode/scan/

URL Parameters

Parameter	Required	Description
`account_slug`	Yes	Account slug for which the scan is to be made.

Request payload

{
  "barcode": "873469898737",
  "scannedAt": "2023-03-04T13:30:00Z",
  "direction": "in",
  "forceScan": false,
}

Field	Type	Description
`barcode`	string	The barcode to be scanned.
`scanned_at`	datetime	The desired date / time in ISO8601 format of when the scan should be happening. If not specified, the scan is assumed to take place at the time the API is called.
`direction`	string	Either "in" or "out". Used in case it is required to register the ticket holder both entering and leaving the venue. If not specified, the scanning behaves as if the ticket holder is attempting to enter the venue.
`forceScan`	boolean	If set to true, it will redeem the barcode regardless of it being valid at the time of scan.

Example output

The exact structure of response payload is defined in section "Scan Result Type".

{
    "status": "success",
    "reason": "Barcode 8972467863 is Valid",
    "errorCode": null,
    "overtimeSeconds": 0,
    "remainingSeconds": null,
    "product": {
        "id": "ab37120c-d67b-4b6d-a5d8-f5c9264375c3",
        "name": {
            "en": "Adult day ticket",
            "de": "Tageskarte für Erwachsene"
        }
    },
    "order": {
        "eventDate": "2023-03-04",
        "startTime": "10:00:00",
        "endTime": "11:00:00",
    },
    "ticket": {
        "validFrom": "2023-03-04T00:00:00+01:00",
        "validTo": "2023-03-04 23:59:59.999999+01:00",
        "priceBeforeDiscount": "23.50",
        "price": "23.50",
        "extraInfo": {
            "buyerFirstName": "John",
            "buyerLastName": "Smith"
        },
    },
    "customer": {
        "email": "john.smith@acme.co",
        "language": "en"
    }
}