This documentation describes the implementation of the REST Tickets API, which is designed for managing and reading data about tickets recorded in Retino. Communication takes place via JSON for input and output. The API is stateless – each request must be authorized with an API token in the request header.
Authentication
Authentication is performed using a token that you can find in Settings > API > API token. Then send this token in every request to the Tickets API in the Authentication header in the following format:
Authentication: Token [Your API token]
Each user in your account has their own token assigned. If you have multiple accounts under one user in Retino, you will have a different token for each Retino account.
Token Renewal
WARNING: if you renew the token, the original token will be immediately invalid, so the integration with your system will have downtime until you replace the token with a new one.
Endpoints Overview
Below is a list of endpoints provided by the Tickets API. The complete technical reference for the Tickets API, containing a precise description of data types, can be found at app.retino.com/api/docs/.
Endpoint | HTTP Method | Description |
| GET | List of all tickets with filtering options |
| POST | Create a new ticket |
| GET | Search tickets by content |
| GET | Ticket detail by ID |
| PUT | Complete update of a ticket |
| PATCH | Partial update of a ticket |
| POST | Close a ticket |
| GET | List of products in a ticket |
| POST | Add a product to a ticket |
| GET | Product detail in a ticket |
| PUT/PATCH | Update a product in a ticket |
| DELETE | Remove a product from a ticket |
| POST | Create an internal note for a ticket |
| GET | List of ticket states |
| GET | List of tags for tickets |
| GET | List of ticket types |
| GET | List of users (agents) |
| GET | List of custom fields for tickets |
| GET | List of custom fields for products |
| GET | List of shipping routes |
| GET | List of shipping types |
| GET | List of refund accounts |
| PATCH | Update a credit note |
Detailed Endpoint Descriptions
List of Tickets
GET
/tickets
Use this endpoint to retrieve data about all tickets. You can filter and sort them by creation date, modification date, and closing date.
Tip: For incremental changes, we recommend creating a webhook instead and having machine-readable data about tickets sent in real time.
Filtering Parameters
created_at_from- filters tickets created after the specified dateupdated_at_from- filters tickets modified after the specified dateclosed_at_from- filters tickets closed after the specified dateis_closed- filters closed/open tickets (boolean)
Example
Request
curl -X GET "https://app.retino.com/api/v2/tickets" -H "Authorization: Token [Your API token]"
Response
{ "count": 1, "current_page": 1, "total_pages": 1, "results": [ { "id": "8fad1c8d-3740-4aab-a224-c0ef379ea216", "code": "20210001", "state": "4531636a-108f-4ae3-abff-367901418600", "tags": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5", "owner": "e342f794-7b11-4acc-a46e-784a74a30af2", "bound_order": null, "products": [ { "id": "09c69980-299d-4d37-81d5-ed18c9565856", "bound_order_item": null, "price": { "with_vat": "990000000.0000", "without_vat": null, "vat": null }, "files": [], "name": "Apollo 11", "manufacturer": "NASA", "category": "Rakety", "product_id": "#1", "variant": "XL", "ean": "", "serial": null, "amount": "1.0000", "custom_fields": { "1b8508b0-ba85-427c-b23c-ae739453b0cd": "74ea523e-ea95-44d4-85ff-758c485ff77d" } } ], "shipping": [], "customer": { "name": "Vladimír Remek", "email": "[email protected]", "phone": "987654321" }, "currency": "CZK", "language": "cs", "country": "CZ", "order_id": "234567", "order_date": "2020-09-09T00:00:00.000Z", "customer_rating": null, "customer_rating_comment": null, "custom_fields": { "resolve_by": "2020-10-08" }, "verification_state": "VERIFIED_AUTOMATICALLY", "is_unread": false, "created_at": "2020-09-24T11:30:53.210107+02:00", "updated_at": "2020-09-24T11:30:53.525472+02:00", "closed_at": null } ]}
Create a Ticket
POST
/tickets
Used to create a new ticket. The request must include at least customer information, currency, language, and other required data according to the documentation.
Example
Request
curl -X POST \ -H 'Authorization: Token [Your API token]' \ -H "Content-type: application/json" \ -d '{ "customer": { "name": "Jan Novák", "email": "[email protected]", "phone": "123456789" }, "currency": "CZK", "language": "cs", "country": "CZ", "order_id": "123456", "order_date": "2025-01-15T00:00:00.000Z", "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5" }' \ https://app.retino.com/api/v2/tickets
Search Tickets
GET
/tickets/search
Used to search for tickets by customer information, products, or associated shipping. For example, this way you can find all tickets related to one order. Returns a paginated list of tickets.
Example
Request
curl -X GET "https://app.retino.com/api/v2/tickets/search?search=Vladimir+Remek" -H "Authorization: Token [Your API token]"
Response
{ "count": 1, "current_page": 1, "total_pages": 1, "results": [ { "id": "8fad1c8d-3740-4aab-a224-c0ef379ea216", "code": "20210001", "state": "4531636a-108f-4ae3-abff-367901418600", "tags": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5", "owner": "e342f794-7b11-4acc-a46e-784a74a30af2", "bound_order": null, "products": [ // Product detail ], "shipping": [], "customer": { "name": "Vladimír Remek", "email": "[email protected]", "phone": "987654321" }, // Other ticket details } ]}
Ticket Detail
GET
/tickets/[id]
Used to retrieve data about one specific ticket by ID.
Example
Request
curl -X GET "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216" -H "Authorization: Token [Your API token]"
Update a Ticket
PUT / PATCH
/tickets/[id]
Used to modify ticket data. You can edit the state, type, assigned agent, customer information, language, currency, country, and custom fields. The PUT method requires all mandatory parameters, PATCH allows you to update only specific fields.
Values that are primary keys of entities (state, type, owner, etc.) can be found in the address bar of the respective entity in the administration or can be obtained using the respective API endpoints for entity lists.
Example
Request
curl -X PATCH \ -H 'Authorization: Token [Your API token]' \ -H "Content-type: application/json" \ -d '{"state": "b3d97cdc-a2d8-4fcc-96f0-1ac91b47d8d3"}' \ https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216
Close a Ticket
POST
/tickets/[id]/close
Used to close a ticket. If you have automation set up for closing a ticket, it will be triggered, which may initiate, for example, sending a rating survey.
Example
Request
curl -X POST "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/close" -H "Authorization: Token [Your API token]"
List of Products in a Ticket
GET
/tickets/[ticket_id]/products
Used to retrieve a list of all products in a specific ticket.
Example
Request
curl -X GET "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/products" -H "Authorization: Token [Your API token]"
Add a Product to a Ticket
POST
/tickets/[ticket_id]/products
Used to add a new product to an existing ticket.
Example
Request
curl -X POST \ -H 'Authorization: Token [Your API token]' \ -H "Content-type: application/json" \ -d '{ "name": "MacBook Pro", "amount": "1.0000", "price": { "with_vat": "45000.0000" }, "product_id": "MBP-2024", "manufacturer": "Apple", "category": "Notebooky", "variant": "Space Black" }' \ https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/products
Product Detail in a Ticket
GET
/tickets/[ticket_id]/products/[id]
Used to retrieve detailed information about a specific product in a ticket.
Example
Request
curl -X GET "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/products/09c69980-299d-4d37-81d5-ed18c9565856" -H "Authorization: Token [Your API token]"
Update a Product
PUT / PATCH
/tickets/[ticket_id]/products/[id]
Used to update product information in a ticket. The PUT method requires all mandatory parameters, PATCH allows you to update only selected fields.
Example
Request
curl -X PATCH \ -H 'Authorization: Token [Your API token]' \ -H "Content-type: application/json" \ -d '{ "amount": "2.0000", "price": { "with_vat": "90000.0000" } }' \ https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/products/09c69980-299d-4d37-81d5-ed18c9565856
Remove a Product
DELETE
/tickets/[ticket_id]/products/[id]
Used to remove a product from a ticket.
Example
Request
curl -X DELETE "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/products/09c69980-299d-4d37-81d5-ed18c9565856" -H "Authorization: Token [Your API token]"
Create an Internal Note
POST
/internal-note
Used to add an internal note to a ticket. Internal notes are visible only to agents, not to customers.
Example
Request
curl -X POST \ -H 'Authorization: Token [Your API token]' \ -H "Content-type: application/json" \ -d '{ "ticket": "8fad1c8d-3740-4aab-a224-c0ef379ea216", "text": "Note about the ticket that the customer will not see." }' \ https://app.retino.com/api/v2/internal-noteUpdate a Credit Note
PATCH
/retino-credit-notes/[id]
Used to update a credit note, primarily to add a credit note file from managing credit notes with your own ERP system.
Example
Request
curl -X PATCH \ -H 'Authorization: Token [Your API token]' \ -H "Content-type: application/json" \ -d '{ "file_base64": "JVBERi0xLjUKJdDUxdgKNSAwIG9iago8PC9GaWx0ZXIv..." }' \ https://app.retino.com/api/v2/retino-credit-notes/5cae6caf-c1cb-49ed-96bd-2d2837765ffc
List of Ticket States
GET
/states
Used to retrieve a list of all ticket states in the account. These states can be used when creating or updating tickets.
Example
Request
curl -X GET "https://app.retino.com/api/v2/states" -H "Authorization: Token [Your API token]"
List of Tags
GET
/tags
Used to retrieve a list of all tags that can be assigned to tickets.
Example
Request
curl -X GET "https://app.retino.com/api/v2/tags" -H "Authorization: Token [Your API token]"
List of Ticket Types
GET
/types
Used to retrieve a list of all ticket types in the account. These types can be used when creating or updating tickets.
Example
Request
curl -X GET "https://app.retino.com/api/v2/types" -H "Authorization: Token [Your API token]"
List of Users
GET
/users
Used to retrieve a list of all users (agents) in the account. These users can be assigned as ticket owners.
Example
Request
curl -X GET "https://app.retino.com/api/v2/users" -H "Authorization: Token [Your API token]"
List of Custom Fields for Tickets
GET
/custom-fields
Used to retrieve a list of all custom fields for tickets. These fields can be used when creating or updating tickets.
Example
Request
curl -X GET "https://app.retino.com/api/v2/custom-fields" -H "Authorization: Token [Your API token]"
List of Custom Fields for Products
GET
/product-custom-fields
Used to retrieve a list of all custom fields for products. These fields can be used when creating or updating products in tickets.
Example
Request
curl -X GET "https://app.retino.com/api/v2/product-custom-fields" -H "Authorization: Token [Your API token]"
List of Shipping Routes
GET
/shipping-routes
Used to retrieve a list of available shipping routes for selecting a carrier when sending products.
Example
Request
curl -X GET "https://app.retino.com/api/v2/shipping-routes" -H "Authorization: Token [Your API token]"
List of Shipping Types
GET
/shipping-types
Used to retrieve a list of shipping types that are available in the account.
Example
Request
curl -X GET "https://app.retino.com/api/v2/shipping-types" -H "Authorization: Token [Your API token]"
List of Refund Accounts
GET
/refund-accounts
Used to retrieve a list of bank accounts for refunds.
Example
Request
curl -X GET "https://app.retino.com/api/v2/refund-accounts" -H "Authorization: Token [Your API token]"
Pagination
Paginated endpoints return the total number of returned results and pages in the response. Such endpoints then accept the page and page_size arguments in the query.
Example
Request
curl -X GET "https://app.retino.com/api/v2/tickets?page=2&page_size=10" -H "Authorization: Token [Your API token]"
Response
{ "count": number, "current_page": number, "total_pages": number, "results": [...data...]}
Best Practices
Webhooks vs. Polling - For receiving updates about tickets, we recommend using webhooks instead of regularly querying the API.
Rate limiting - The API has limits on the number of requests you can send in a certain time interval. Implement proper rate limit handling and retry mechanisms.
Storing Entity IDs - For editing tickets, you will need entity IDs (states, types, etc.). It's advisable to store this data and regularly update it.
Result Pagination - When working with a larger number of tickets, always use pagination to optimize performance.
Common Issues
401 Unauthorized - Check that you are sending the correct API token in the request header.
403 Forbidden - Check that your user has sufficient permissions to access the requested data.
429 Too Many Requests - You have exceeded the request limit. Implement exponential backoff for retrying requests.
Technical Reference
For a detailed description of all endpoints, parameters, data models, and filtering options, see our Tickets API reference.