forked from CGM_Public/pretix_original
7e60d13910
* Fix #3984 -- API: Add phone to customer resource * add "phone": None to test --------- Co-authored-by: Mira Weller <weller@rami.io>
272 lines
9.4 KiB
ReStructuredText
272 lines
9.4 KiB
ReStructuredText
.. _`rest-customers`:
|
|
|
|
Customers
|
|
=========
|
|
|
|
Resource description
|
|
--------------------
|
|
|
|
The customer resource contains the following public fields:
|
|
|
|
.. rst-class:: rest-resource-table
|
|
|
|
===================================== ========================== =======================================================
|
|
Field Type Description
|
|
===================================== ========================== =======================================================
|
|
identifier string Internal ID of the customer
|
|
external_identifier string External ID of the customer (or ``null``). This field can
|
|
be changed for customers created manually or through
|
|
the API, but is read-only for customers created through a
|
|
SSO integration.
|
|
email string Customer email address
|
|
phone string Customer phone number
|
|
name string Name of this customer (or ``null``)
|
|
name_parts object of strings Decomposition of name (i.e. given name, family name)
|
|
is_active boolean Whether this account is active
|
|
is_verified boolean Whether the email address of this account has been
|
|
verified
|
|
last_login datetime Date and time of last login
|
|
date_joined datetime Date and time of registration
|
|
locale string Preferred language of the customer
|
|
last_modified datetime Date and time of modification of the record
|
|
notes string Internal notes and comments (or ``null``)
|
|
password string Can only be set during creation of a new customer, will
|
|
not be included in any responses.
|
|
===================================== ========================== =======================================================
|
|
|
|
.. versionadded:: 4.0
|
|
|
|
.. versionchanged:: 4.3
|
|
|
|
Passwords can now be set through the API during customer creation.
|
|
|
|
.. versionchanged:: 2024.3
|
|
|
|
The attribute ``phone`` has been added.
|
|
|
|
Endpoints
|
|
---------
|
|
|
|
.. http:get:: /api/v1/organizers/(organizer)/customers/
|
|
|
|
Returns a list of all customers registered with a given organizer.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/organizers/bigevents/customers/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"count": 1,
|
|
"next": null,
|
|
"previous": null,
|
|
"results": [
|
|
{
|
|
"identifier": "8WSAJCJ",
|
|
"external_identifier": null,
|
|
"email": "customer@example.org",
|
|
"phone": "+493012345678",
|
|
"name": "John Doe",
|
|
"name_parts": {
|
|
"_scheme": "full",
|
|
"full_name": "John Doe"
|
|
},
|
|
"is_active": true,
|
|
"is_verified": false,
|
|
"last_login": null,
|
|
"date_joined": "2021-04-06T13:44:22.809216Z",
|
|
"locale": "de",
|
|
"last_modified": "2021-04-06T13:44:22.809377Z",
|
|
"notes": null
|
|
}
|
|
]
|
|
}
|
|
|
|
:query integer page: The page number in case of a multi-page result set, default is 1
|
|
:query string email: Only fetch customers with this email address
|
|
:param organizer: The ``slug`` field of the organizer to fetch
|
|
:statuscode 200: no error
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
|
|
|
|
.. http:get:: /api/v1/organizers/(organizer)/customers/(identifier)/
|
|
|
|
Returns information on one customer, identified by its identifier.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/organizers/bigevents/customers/8WSAJCJ/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"identifier": "8WSAJCJ",
|
|
"external_identifier": null,
|
|
"email": "customer@example.org",
|
|
"phone": "+493012345678",
|
|
"name": "John Doe",
|
|
"name_parts": {
|
|
"_scheme": "full",
|
|
"full_name": "John Doe"
|
|
},
|
|
"is_active": true,
|
|
"is_verified": false,
|
|
"last_login": null,
|
|
"date_joined": "2021-04-06T13:44:22.809216Z",
|
|
"locale": "de",
|
|
"last_modified": "2021-04-06T13:44:22.809377Z",
|
|
"notes": null
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer to fetch
|
|
:param identifier: The ``identifier`` field of the customer to fetch
|
|
:statuscode 200: no error
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
|
|
|
|
.. http:post:: /api/v1/organizers/(organizer)/customers/
|
|
|
|
Creates a new customer. In addition to the fields defined on the resource, you can pass the field ``send_email``
|
|
to control whether the system should send an account activation email with a password reset link (defaults to
|
|
``false``).
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /api/v1/organizers/bigevents/customers/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"email": "test@example.org",
|
|
"phone": "+493012345678",
|
|
"password": "verysecret",
|
|
"send_email": true
|
|
}
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 201 Created
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"identifier": "8WSAJCJ",
|
|
"external_identifier": null,
|
|
"email": "test@example.org",
|
|
"phone": "+493012345678",
|
|
...
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer to create a customer for
|
|
:statuscode 201: no error
|
|
:statuscode 400: The customer could not be created due to invalid submitted data.
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.
|
|
|
|
.. http:patch:: /api/v1/organizers/(organizer)/customers/(identifier)/
|
|
|
|
Update a customer. You can also use ``PUT`` instead of ``PATCH``. With ``PUT``, you have to provide all fields of
|
|
the resource, other fields will be reset to default. With ``PATCH``, you only need to provide the fields that you
|
|
want to change.
|
|
|
|
You can change all fields of the resource except the ``identifier``, ``last_login``, ``date_joined``,
|
|
``name`` (which is auto-generated from ``name_parts``), and ``last_modified`` fields.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
PATCH /api/v1/organizers/bigevents/customers/8WSAJCJ/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
Content-Type: application/json
|
|
Content-Length: 94
|
|
|
|
{
|
|
"email": "test@example.org"
|
|
}
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"identifier": "8WSAJCJ",
|
|
"external_identifier": null,
|
|
"email": "test@example.org",
|
|
"phone": "+493012345678",
|
|
…
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer to modify
|
|
:param identifier: The ``identifier`` field of the customer to modify
|
|
:statuscode 200: no error
|
|
:statuscode 400: The customer could not be modified due to invalid submitted data
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to change this resource.
|
|
|
|
.. http:post:: /api/v1/organizers/(organizer)/customers/(identifier)/anonymize/
|
|
|
|
Anonymize a customer. Deletes personal data and disconnects from existing orders.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /api/v1/organizers/bigevents/customers/8WSAJCJ/anonymize/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"identifier": "8WSAJCJ",
|
|
"external_identifier": null,
|
|
"email": null,
|
|
"phone": null,
|
|
…
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer to modify
|
|
:param identifier: The ``identifier`` field of the customer to modify
|
|
:statuscode 200: no error
|
|
:statuscode 400: The customer could not be modified due to invalid submitted data
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to change this resource.
|