Orders

An order is a collection of products or tickets created by a consumer. It is part of our main purchase flow where a consumer adds products to a basket, creates an order from the products in the basket, and pays for the order.

Placing a new order

Place a new order by defining products, consumer details and some additional data to administer the order.

This request can be authenticated using Basic access authorization or a Bearer token, in addition to a Cognito token. When including a Cognito token in the request, the consumer represented by the token will be able to manage this order after creation. Other consumers will receive an email confirmation of their order containing a link with an Order token to manage their order.

Request data

Field name Type   Description
products List of Product selection List of products with a quantity. Optionally you can provide a List of Ticket consumer objects. Note that the length of the list should be equal to the quantity of the products. All products must be part of the same Event.
tickets Ticket references List of tickets to transfer to a new order and new owner. All tickets should be part of the same order. You cannot provide both products and tickets in a single order.
consumer Consumer A consumer object, describing the information of the consumer for whom the order is being placed.
payment_method String The selected payment method. Optional for free orders.
shipping_method String or Shipping The selected shipping method uid. Optional. Alternatively, you may provide a Consumer object in case the delivery address is different from the consumer address. In this case, only address-related fields are required and stored in our system.
external_purchases List of External purchase A list of external purchases. Optional.
external_reference String(32) 32 characters to use as your own reference. Optional.
redirect_url String(255) 255 character field for redirecting clients back to your site, this overrides the default redirect_url set in the backoffice. Optional.
check_consecutive_seats Boolean Defaults to true. If the event has seating enabled and the value is true, you will receive an INSUFFICIENT_CONSECUTIVE_SEATS error when there are not enough consecutive seats available and the order will not be created. This ensures that people that want to sit next to each other don’t end up in different rows.
vouchers List of strings List of voucher codes that open an access to specific sales or provide discounts.
currency String (ISO 4217) Currency code (See Amount). Optional.
opt_in Boolean Opt-in choice (See Event).
captcha String Optional captcha token.

Examples

Create an order from a product selection

[POST] https://shopping-api.paylogic.com/orders
{
    "products": [
        {
            "product": "https://shopping-api.paylogic.com/products/12365478654238976585643567854323",
            "quantity": 3
        },
        {
            "product": "https://shopping-api.paylogic.com/products/456ghtr45tg678fe5rf456yhgbvsw3lh",
            "quantity": 1,
            "consumer": {
                "address": "Some street 31",
                "city": "Some city",
                "country": "US",
                "date_of_birth": "1990-01-01",
                "email": "john.smith@example.com",
                "first_name": "John",
                "last_name": "Smith",
                "gender": 1,
                "postal_code": "1234",
                "state": "UT",
                "language": "en"
            }
        }
    ],
    "consumer": {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1986-12-30",
        "email": "john.doe@paylogic.eu",
        "gender": "1",
        "address": "Nieuwe Boteringestraat 28",
        "postal_code": "9716 JJ",
        "city": "Groningen",
        "country": "NL",
        "ip": "192.168.1.1"
    },
    "payment_method": "ghr57d5h3gd162fb35c5a3db57ghrydg",
    "shipping_method": {
        "uid": "87a5quvndhe162fb357alt872705zr2j",
        "consumer" : {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@paylogic.com",
            "gender": 1,
            "address": "Some street for shipping 2",
            "city": "Some other city",
            "country": "US",
            "postal_code": "02145",
            "state": "MA"
        }
    },
    "external_purchases": [
        {
            "title": {
                "en": "External purchase"
            },
            "product_reference": "External purchase product A",
            "quantity": 3,
            "unit_price": {
                "currency": "EUR",
                "amount": 50.00
            }
        }
    ],
    "external_reference": "CO-118",
    "redirect_url": "http://www.example.com/redirect_url/",
    "check_consecutive_seats": "true"
}

Create an order from a basket

When you create an order from a basket, the order will inherit all data that was already administered in the basket. All data previously administered in the basket can be overwritten while creating the order.

[POST] https://shopping-api.paylogic.com/orders
{
    "basket": "https://shopping-api.paylogic.com/basket/d2e37ee17474417a87259b02b674da9b",
    "payment_method": "ghr57d5h3gd162fb35c5a3db57ghrydg",
    "shipping_method": "87a5quvndhe162fb357alt872705zr2j",
}

Transfer tickets

When transferring tickets, all tickets have to belong to the same order. This request can be authenticated using Basic access authorization, in addition to an Order token or Cognito token. The Order token or Cognito token must have access to the original order in order to allow a transfer.

[POST] https://shopping-api.paylogic.com/orders
{
    "tickets": [
        "https://shopping-api.paylogic.com/tickets/a2e37ee17474417a87259b02b674da9a",
        "https://shopping-api.paylogic.com/tickets/12365478654238976585643567854323",
    ],
    "consumer": {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1986-12-30",
        "email": "john.doe@paylogic.eu",
        "gender": "1",
        "address": "Nieuwe Boteringestraat 28",
        "postal_code": "9716 JJ",
        "city": "Groningen",
        "country": "NL",
        "ip": "192.168.1.1"
    },
    "payment_method": "ghr57d5h3gd162fb35c5a3db57ghrydg",
    "shipping_method": "87a5quvndhe162fb357alt872705zr2j",
}

Captcha

Placing an order may be rate-limited by the application and a captcha has to be resolved by the consumer. In this case Storefront exposes the captcha provider and public key.

Example request

{
    "products": [
        {
            "product": "https://shopping-api.paylogic.com/products/12365478654238976585643567854323",
            "quantity": 3
        },
    "captcha": "<reCAPTCHA response>",
    ...
}

Error types

Error type codes can be used to dispatch the errors on the client side. These errors are related to the order creation. See bill errors.

Type HTTP code Description
FORBIDDEN 403 Forbidden.
NOT_FOUND 404 Not found.
BAD_REQUEST 400 Bad request.
PAYMENT_METHOD_MISSING 400 A payment method is needed for the creation of an order. Please retrieve a bill for the selected products to see which payment methods are available.
EMPTY_BASKET 400 You are trying to create an order with no products.
CONSUMER_MISSING 400 Not all necessary consumer data was provided. Please check the documentation to see which data to provide.
CONSTRAINT_VIOLATION 400 Generic constraint violation.
NO_TICKETS_OR_PRODUCTS_PROVIDED 400 No tickets or products provided.
BOTH_TICKETS_AND_PRODUCTS_PROVIDED 400 Both tickets or products provided, while only one or the other is allowed.
TICKET_ERROR 400 When creating Transfer Approvals: Ticket or transfer approval is not in a valid state.
TICKET_NOT_AVAILABLE 400 Provided ticket is not valid or not found.
NO_CONSUMER_URI_OR_INFO_PROVIDED 400 Provided consumer information is not valid, or a consumer is not found.
TICKET_CONSUMER_ERROR 400 Ticket consumer information is not valid.
INSUFFICIENT_CONSECUTIVE_SEATS 409 There are not enough seats available in the same row. The order has been cancelled.
VOUCHER_INVALID 400 Voucher code is invalid.
CAPTCHA_INVALID 403 Captcha token is invalid.
CAPTCHA_RATE_LIMIT_REACHED 400 Order creation rate limit has been exceeded, please resolve captcha.
CAPTCHA_INVALID_DOMAIN 403 Captcha token is resolved for the domain that is not allowed by the application.
10MER 403 With this combination of data, it is not possible to buy tickets for this event. Please contact the Paylogic Customer Service (please supply calling code: 10MER)

Retrieve a single order

Retrieve the details of a single order using an order reference.

Authentication

The retrieval of an order can be authenticated in multiple ways.

  • Basic access authorization: The application must have permission to access this order.
  • Bearer token: The application will have access if it created the order.
  • Cognito token: The user represented by the token must be the creator of the order.
  • Order token: The token has to match the order token in our system.

Response

Field name Type Description
uid String A machine readable id for this order, used in communication with the API.
reference String A human readable id for this order, used in communication with consumers.
external_reference String 32 character field for your own purpose.
redirect_url String 255 character field for redirecting clients back to your site, this overrides the default redirect_url set in the backoffice.
created_date Datetime The date and time the order was created.
status String The status of the order. See Order statuses for the values.
product_selection List of Product selection List of products with a quantity. There is also an optional parent attribute when combo products are used.
consumer Order consumer An order consumer object, representing the consumer data as provided when placing the order.
payment_method Payment method The payment method selected when placing the order.
shipping_method Shipping method The shipping method selected when placing the order. If none is selected, the key will be included but the value will be an empty object.
product_total Amount The total value of all products.
service_costs Amount The service costs included by the merchant and Paylogic.
grand_total Amount The grand total the consumer has to pay.
external_purchases External purchase A list of external purchases.
legal_info Legal info Legal information for this order.

Order statuses

Status Description
pending We are waiting for the payment to arrive.
completed The payment has arrived.
canceled The order is canceled and no longer valid.

Embedded resources

  • shop:product: a list of products in this order. See Product.
  • shop:ticket: a list of tickets in this order. See Tickets.

Example

[GET] https://shopping-api.paylogic.com/orders/87a2195h3gd162fb35c5a3dbd7bapo1l
{
    "_links": {
        "curies": [{ "name": "shop", "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html", "templated": true, "type": "text/html" }],
        "self": { "href": "https://shopping-api.paylogic.com/orders/87a2195h3gd162fb35c5a3dbd7bapo1l" },
        "profile": { "href": "https://shopping-api-docs.paylogic.com/documentation/orders.html", "type": "text/html" },
        "payment": { "href": "https://payments.paylogic.com?redirect=https://psp.paylogic.com/consumer/123", "type": "text/html" },
        "shop:etickets": { "href": "https://download.paylogic.com/eticket/sdfsdf235r245wsdgfw5235", "type": "text/html" },
        "shop:ordercancellation": { "href": "https://shopping-api.paylogic.com/ordercancellation", "type": "text/html" }
    },
    "uid": "87a2195h3gd162fb35c5a3dbd7bapo1l",
    "reference": "525743",
    "created_date": "2014-05-01T12:15:00Z",
    "status": "pending",
    "product_selection": [
        {
            "product": "https://shopping-api.paylogic.com/products/12365478654238976585643567854323",
            "quantity": 3,
            "unit_price": {"currency": "EUR", "amount": "5.45"},
            "total": {"currency": "EUR", "amount": "16.35"}
        },
        {
            "product": "https://shopping-api.paylogic.com/products/456ghtr45tg678fe5rf456yhgbvsw3lh",
            "quantity": 1,
            "unit_price": {"currency": "EUR", "amount": "1.00"},
            "total": {"currency": "EUR", "amount": "1.00"}
        },
        {
            "parent": "https://shopping-api.paylogic.com/products/456ghtr45tg678fe5rf456yhgbvsw3lh",
            "product": "https://shopping-api.paylogic.com/products/267arnr45tg984rd5rf456opshwks0ol",
            "quantity": 1,
            "unit_price": {"currency": "EUR", "amount": "1.23"},
            "total": {"currency": "EUR", "amount": "1.23"}
        }
    ],
    "consumer": {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1986-12-30",
        "email": "john.doe@paylogic.eu",
        "gender": 1,
        "address": "Nieuwe Boteringestraat 28",
        "postal_code": "9716 JJ",
        "city": "Groningen",
        "country": "NL",
        "ip": "192.168.1.1"
    },
    "payment_method": {
        "uid": "ghr57d5h3gd162fb35c5a3db57ghrydg",
        "name": {"en": "iDeal", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
        "image": "https://static.paylogic.com/ideal.jpg",
        "costs": { "amount": 1.00, "currency": "EUR" }
    },
    "shipping_method": {
        "uid": "87a5quvndhe162fb357alt872705zr2j",
        "name": {"en": "Eticket", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
        "costs": { "amount": 0.50, "currency": "EUR" }
    },
    "product_total": { "amount": 13.50, "currency": "EUR" },
    "service_costs": { "amount": 1.50, "currency": "EUR" },
    "grand_total": { "amount": 16.50, "currency": "EUR" },
    "external_purchases": [
        {
            "title": {"en": "External purchase", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
            "product_reference": "External purchase product A",
            "unit_price": { "amount": 50.00, "currency": "EUR" },
            "quantity": 3
        }
    ],
    "external_reference": "CO-115",
    "redirect_url": "http://example.com/redirect_url",
    "legal_info": {
        "registration_id": "reg123456789",
        "display_imprint": false,
        "statutory_city": "Koeln",
        "telephone_number": "+123456789",
        "doing_business_as": "Mega Corporation",
        "platform": {
            "registration_id": "ABCDEF0123456789",
            "legal_representative": "Kyle Reece",
            "legal_phrase": "The red fox jumped over brown dog",
            "customer_service_email": "industrious@cs.com",
            "telephone_number": "+123123123987",
            "vat_id": "FEDDEF123321",
            "_links": {
                "shop:customer_service_url": {
                    "href": "https://customer.service.url/follow/me"
                },
                "shop:logo_url": {
                    "href": "https://logo.url/follow/me"
                },
                "curies": [
                    {
                        "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html",
                        "type": "text/html",
                        "name": "shop",
                        "templated": true
                    }
                ],
                "shop:terms_url": {
                    "href": "https://terms.url/follow/me",
                    "templated": true
                },
                "shop:privacy_url": {
                    "href": "https://privacy.url/follow/me",
                    "templated": true
                },
                "shop:cookie_url": {
                    "href": "https://cookie.url/follow/me",
                    "templated": true
                }
            },
            "company_name": "Industrious Corporation",
            "statutory_zip": "RX 4500",
            "statutory_address": "204C Niklaus Wirth avenue",
            "statutory_city": "Utrecht",
            "public_email": "domain@address.com",
            "display_powered_by": false
        },
        "legally_represented_by": "Hannes Strauss",
        "statutory_zip": "NX 2162",
        "statutory_address": "Lange Strasse 24",
        "vat_id": "vat123456789",
        "public_email": "mailme@com.de",
        "display_imprint": true,
        "imprint_additional_info": {
            "es": "",
            "en": "Legal information\nRequired in Germany.",
            "nl": "",
            "de": "",
            "fr": "Rechtsinformation\nIn Deutschland erforderlich.",
            "pt": "",
            "tr": ""
        }
    },
    "_embedded": {
        "shop:product": [
            // See "Embedded resources" above.
        ],
        "shop:ticket": [
            // See "Embedded resources" above.
        ],
        "shop:customer_service": {
            "email": "customerservice@paylogic.com"
        },
    }
}

Retrieve multiple orders

Retrieve multiple orders in a single request with optional filtering. The result is ordered by Order ID, lowest first.

This resource uses Pagination.

Filtering

Field name Description
event Event URI exact match
event__in Event URI in (list)
external_reference Event UID exact match
state Order state exact match
state__ne Order state not equal
state__in Order state in (list)
created__lt Created less-than
created__lte Created less-than or equal
created__gt Created greater than
created__gte Created greater than or equal

Response

The response will contain a list of orders and Pagination data.

For documentation on data in shop:order: see Retrieve a single order above.

[GET] https://shopping-api.paylogic.com/orders?state=completed
{
    "_links": {
        "self": { "href": "https://shopping-api.paylogic.com/orders?page=2" },
        "curies": [
            { "name": "shop", "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html", "templated": true, "type": "text/html" },
        ],
        "profile": { "href": "https://shopping-api-docs.paylogic.com/documentation/orders.html", "type": "text/html" },
        "search": { "href": "https://shopping-api.paylogic.com/orders?state=completed", "templated": true },
        "first": { "href": "https://shopping-api.paylogic.com/products" },
        "prev": { "href": "https://shopping-api.paylogic.com/products?page=1" },
        "next": { "href": "https://shopping-api.paylogic.com/products?page=3" },
        "last": { "href": "https://shopping-api.paylogic.com/products?page=7" }
    },
    "item_count": 128,
    "_embedded": {
        "shop:order": [
            { ... },
            { ... },
        ]
    }
}