********* Consumers ********* The consumers resource is a collection resource, where a new :doc:`/documentation/consumer` revision may be created. The latest consumer information is available by a GET request to :doc:`/documentation/consumer`, :doc:`/documentation/orders` or :doc:`/documentation/tickets` via the ``consumer`` attribute. .. note:: Not all events support ticket consumer information (personalization information) so posting to this resource with existing tickets is only needed when the event supports personalization. .. note:: POSTing consumer information with existing tickets is only possible within the personalization period (see :doc:`event`). Accepted methods ================ * **GET**: Retrieve the list of consumers. * **POST**: Place a new consumer information. Accepted query parameters ========================= ======================= ======================================== Field name Description ======================= ======================================== email Email exact match email__startswith Email starts with first_name First name exact match first_name__startswith First name starts with last_name Last name exact match last_name__startswith Last name starts with date_of_birth Date of birth exact match date_of_birth__lt Date of birth less than date_of_birth__lte Date of birth less than or equals date_of_birth__gt Date of birth greater than date_of_birth__gte Date of birth greater than or equals gender Gender exact match postal_code Postal code match city City match city__startswith City starts with country Country exact match state State exact match reference Reference exact match external_reference External reference exact match ======================= ======================================== Data ==== ========== ======== ==================================================== Field name Type Description ========== ======== ==================================================== item_count Integer The number of consumers in the collection. ========== ======== ==================================================== Link relations ============== * Search * First * Prev * Next * Last Embedded resources ================== * :doc:`Consumer (list) `. Example representation ====================== .. code-block:: bash [GET] https://shopping-api.paylogic.com/consumers?page=2 .. code-block:: javascript { "_links": { "self": { "href": "https://shopping-api.paylogic.com/consumers?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/consumers.html", "type": "text/html" }, "search": { "href": "https://shopping-api.paylogic.com/consumers{?first_name,last_name}", "templated": true }, "first": { "href": "https://shopping-api.paylogic.com/consumers" }, "prev": { "href": "https://shopping-api.paylogic.com/consumers?page=1" }, "next": { "href": "https://shopping-api.paylogic.com/consumers?page=3" }, "last": { "href": "https://shopping-api.paylogic.com/consumers?page=10" } }, "item_count": 183, "_embedded": { "shop:consumer": [ { "_links": { "curies": [ { "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html", "name": "shop", "templated": true, "type": "text/html" } ], "profile": { "href": "https://shopping-api-docs.paylogic.com/documentation/consumer.html", "type": "text/html" }, "self": { "href": "https://shopping-api.paylogic.com/consumers/cba40d60019448278542c9f5ac1bf7ce" } }, "uid": "cba40d60019448278542c9f5ac1bf7ce", "address": "Some street 31", "city": "Some city", "country": "US", "date_of_birth": "1990-01-01", "email": "john.smith.last@example.com", "first_name": "John", "last_name": "Smith", "gender": 1, "postal_code": "1234", "state": "UT" } ] } } .. _update-consumers: POST behaviour ============== When POSTing to this resource, you are creating a consumer information revision. After POSTing you can always read the consumer information back using the :doc:`consumer` resource. If you provide tickets to attach to a consumer, after POSTing, the consumer information will also be available through the :ref:`ticket resource `. Request body schema ------------------- ========== ========================================= ==================================================== Field name Type Description ========== ========================================= ==================================================== consumers list of :doc:`consumer` List of the consumer information to be saved. ========== ========================================= ==================================================== Constraints ----------- * You have permission to create consumer revisions. * When tickets are provided, tickets' event should support personalization. * When tickets are provided, tickets should be unique within the same call. * When tickets are provided, tickets' event personalization period should include the date and time of the call. Example - Create ticket consumer revision ----------------------------------------- Personal details are supplied with the ticket explicitly. .. code-block:: bash [POST] https://shopping-api.paylogic.com/consumers .. code-block:: javascript { "consumers": [ { "tickets": [ "https://shopping-api.paylogic.com/tickets/5959f610ba0f4b61b30750d5382f228c", "https://shopping-api.paylogic.com/tickets/a2e37ee17474417a87259b02b674da9a" ], "address": "Some other street 32", "city": "Some other city", "country": "UK", "date_of_birth": "1990-01-01", "email": "some.one@example.com", "first_name": "Some", "last_name": "One", "gender": 2, "postal_code": "1235" }, { "tickets": ["https://shopping-api.paylogic.com/tickets/d2f470d7fa574a39860451ef190f5698"], "address": "Yet another street 10", "city": "Yet another city", "country": "UK", "date_of_birth": "1996-07-07", "email": "other.person@example.com", "first_name": "Other", "last_name": "Person", "gender": 2, "postal_code": "1235" } ] } Example - Create implicit ticket consumer revision -------------------------------------------------- Consumer UID is supplied implicitly via the bearer token. In this case personal details are optional. When authorized with the bearer token only one consumer in the payload is allowed. .. code-block:: bash [POST] https://shopping-api.paylogic.com/consumers/ .. code-block:: javascript { "consumers": [ { "tickets": "https://shopping-api.paylogic.com/tickets/a2e37ee17474417a87259b02b674da9a" } ] } POST error handling =================== .. _consumer-errors: Error types ----------- Error type codes can be used to dispatch the errors on the client side. ================================= =================== ========================================================================================================= Type HTTP Code Description ================================= =================== ========================================================================================================= FORBIDDEN 403 Forbidden. NOT_FOUND 404 Not found. BAD_REQUEST 400 Bad request. TICKET_ERROR 400 Ticket is not in a valid state, tickets are not unique or ticket’s product is not in app’s point of sale. INSUFFICIENT_CONSUMER_INFORMATION 400 Provided consumer information is not valid, or a consumer is not found by provided URI. TICKET_NOT_AVAILABLE 400 Provided ticket for binding to a consumer information is not valid or not found. ================================= =================== =========================================================================================================