Support Tickets API

The Tickets API allows you to create, track, and manage support tickets directly from your application. Use it to report payment issues, request refunds, ask integration questions, and communicate with the LuxCore support team — all without leaving your platform.

API Key Scopes

Your API key must have the appropriate scopes to access ticket endpoints:

Scope	Permissions
`tickets.create`	Create new support tickets
`tickets.read`	List tickets, view details, list comments, download attachments
`tickets.update`	Close/reopen tickets, add comments, upload attachments

Contact your account manager or request scope changes via the Dashboard to enable ticket scopes on your API key.

Creating a Ticket

Create a new support ticket with POST /tickets.

curl -X POST "https://api.lux-core.io/api/v1/tickets" \
  -H "X-API-Key: qp_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Payment stuck in pending",
    "description": "Payment pay_123456 has been pending for over 2 hours",
    "category": "payment_issue",
    "payment_id": "pay_123456",
    "requires_refund": false
  }'

Request Body

Field	Type	Required	Description
`title`	string	Yes	Ticket title (max 200 characters)
`description`	string	No	Detailed description of the issue
`category`	string	No	Ticket category (see Categories)
`sub_category`	string	No	Sub-category for further classification
`payment_id`	string	No	Related payment ID
`transaction_id`	string	No	Related transaction ID
`reference`	string	No	Your external reference
`requires_refund`	boolean	No	Whether a refund is required (default: `false`)

Response

{
  "success": true,
  "data": {
    "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Payment stuck in pending",
    "description": "Payment pay_123456 has been pending for over 2 hours",
    "status": "open",
    "category": "payment_issue",
    "sub_category": null,
    "payment_id": "pay_123456",
    "transaction_id": null,
    "reference": null,
    "requires_refund": false,
    "resolution_summary": null,
    "attachments": [],
    "created_at": "2026-02-26T14:30:00.000Z",
    "updated_at": "2026-02-26T14:30:00.000Z",
    "resolved_at": null,
    "last_activity_at": "2026-02-26T14:30:00.000Z"
  }
}

Creating a duplicate ticket for the same payment ID returns a 409 Conflict error. Use a comment on the existing ticket instead.

Listing Tickets

Retrieve a paginated list of your tickets with GET /tickets.

curl -X GET "https://api.lux-core.io/api/v1/tickets?status=open&sort_by=created_at&sort_order=desc&limit=20" \
  -H "X-API-Key: qp_test_your_key"

Query Parameters

Parameter	Type	Default	Description
`status`	string[]	—	Filter by status (can pass multiple: `?status=open&status=in_progress`)
`category`	string[]	—	Filter by category (can pass multiple)
`search`	string	—	Free-text search in title and description (max 100 chars)
`payment_id`	string	—	Filter by related payment ID
`created_after`	string	—	ISO 8601 date — tickets created after this date
`created_before`	string	—	ISO 8601 date — tickets created before this date
`sort_by`	string	`created_at`	Sort field: `created_at`, `updated_at`, `last_activity_at`, `status`
`sort_order`	string	`desc`	Sort order: `asc` or `desc`
`limit`	integer	`20`	Items per page (1–100)
`offset`	integer	`0`	Number of items to skip

Response

{
  "success": true,
  "data": [
    {
      "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Payment stuck in pending",
      "status": "open",
      "category": "payment_issue",
      "payment_id": "pay_123456",
      "requires_refund": false,
      "created_at": "2026-02-26T14:30:00.000Z",
      "updated_at": "2026-02-26T14:30:00.000Z",
      "last_activity_at": "2026-02-26T14:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1,
    "total_pages": 1
  }
}

Getting Ticket Details

Retrieve full details of a specific ticket with GET /tickets/:ticketId.

curl -X GET "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: qp_test_your_key"

Returns the same MerchantTicketResponseDto structure as the create endpoint.

Closing a Ticket

Close an open ticket with POST /tickets/:ticketId/close. You can optionally include a closing comment.

curl -X POST "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/close" \
  -H "X-API-Key: qp_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Issue resolved, closing ticket"
  }'

Only tickets in open, in_progress, waiting_customer, or resolved status can be closed. Attempting to close a ticket in another status returns 400 Bad Request.

Reopening a Ticket

Reopen a resolved or closed ticket with POST /tickets/:ticketId/reopen.

curl -X POST "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reopen" \
  -H "X-API-Key: qp_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Issue persists, reopening"
  }'

Comments

Adding a Comment

Add a comment to an existing ticket with POST /tickets/:ticketId/comments.

curl -X POST "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments" \
  -H "X-API-Key: qp_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Here is the screenshot of the error",
    "attachments": [
      {
        "attachment_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "key": "ticket-api/123/1709912345678-xyz789.png",
        "filename": "error-screenshot.png",
        "content_type": "image/png"
      }
    ]
  }'

Comment Request Body

Field	Type	Required	Description
`body`	string	Yes	Comment text
`attachments`	array	No	Pre-uploaded attachment references (see Attachments)

Each attachment reference requires:

Field	Type	Description
`attachment_id`	string	Attachment ID from the upload-url response
`key`	string	Storage key from the upload-url response
`filename`	string	Original filename
`content_type`	string	MIME content type

Listing Comments

Retrieve comments on a ticket with GET /tickets/:ticketId/comments.

curl -X GET "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments?limit=50&offset=0" \
  -H "X-API-Key: qp_test_your_key"

Comment Response

{
  "success": true,
  "data": [
    {
      "id": 1042,
      "author_type": "merchant",
      "body": "Here is the screenshot of the error",
      "attachments": [
        {
          "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "error-screenshot.png",
          "type": "image/png",
          "size": 245120
        }
      ],
      "created_at": "2026-02-26T15:00:00.000Z",
      "updated_at": "2026-02-26T15:00:00.000Z"
    },
    {
      "id": 1043,
      "author_type": "admin",
      "body": "Thank you, we're investigating the issue",
      "attachments": [],
      "created_at": "2026-02-26T15:10:00.000Z",
      "updated_at": "2026-02-26T15:10:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 2,
    "total_pages": 1
  }
}

Only public comments are returned. Internal team comments are not visible via the API.

Attachments

File attachments use a two-step upload flow: first generate a pre-signed upload URL, then upload the file directly to storage.

Supported File Types

MIME Type	Extension
`image/jpeg`	.jpg, .jpeg
`image/png`	.png
`image/webp`	.webp
`image/gif`	.gif
`application/pdf`	.pdf
`video/mp4`	.mp4
`video/webm`	.webm

Upload Workflow

Generate Upload URL

Call POST /tickets/:ticketId/upload-url with the filename, content type, and optionally file size:

curl -X POST "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/upload-url" \
  -H "X-API-Key: qp_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "receipt.png",
    "content_type": "image/png",
    "file_size": 245120
  }'

Field	Type	Required	Description
`filename`	string	Yes	Original filename (max 255 chars)
`content_type`	string	Yes	MIME type (see Supported File Types)
`file_size`	integer	No	File size in bytes. If provided, must not exceed 10MB (10,485,760 bytes)

Response:

{
  "success": true,
  "data": {
    "upload_url": "https://storage.lux-core.io/support-tickets/ticket-api/123/1709912345678-abc123.png?X-Amz-...",
    "attachment_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "key": "ticket-api/123/1709912345678-abc123.png",
    "expires_in": 300
  }
}

Upload the File

Use the pre-signed upload_url to upload the file directly via HTTP PUT:

curl -X PUT "UPLOAD_URL_FROM_PREVIOUS_STEP" \
  -H "Content-Type: image/png" \
  --data-binary @receipt.png

Reference in Comment

Include the attachment_id, key, filename, and content type when adding a comment:

{
  "body": "Attached the receipt",
  "attachments": [
    {
      "attachment_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "key": "ticket-api/123/1709912345678-abc123.png",
      "filename": "receipt.png",
      "content_type": "image/png"
    }
  ]
}

Upload URLs expire after the time indicated in expires_in (in seconds). Generate a new URL if the previous one has expired.

Downloading Attachments

To download an attachment, request a pre-signed download URL: Ticket-level attachment:

curl -X GET "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/attachments/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-API-Key: qp_test_your_key"

Comment attachment:

curl -X GET "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments/1/attachments/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-API-Key: qp_test_your_key"

Response:

{
  "success": true,
  "data": {
    "download_url": "https://storage.lux-core.io/support-tickets/tickets/1709912345678-abc123.png?X-Amz-...",
    "thumb_url": "https://storage.lux-core.io/support-tickets/tickets/1709912345678-abc123-thumb.png?X-Amz-..."
  }
}

thumb_url is available for image attachments only. It is null for PDFs and videos.

Ticket Statuses

Status	Description
`open`	Ticket created, awaiting support team review
`in_progress`	Support team is actively working on the issue
`waiting_customer`	Support team has responded and is waiting for your input
`on_hold`	Ticket is paused (e.g., waiting for a third party)
`resolved`	Issue has been resolved by the support team
`closed`	Ticket is closed (by merchant or after resolution)
`canceled`	Ticket was canceled

Status Lifecycle

open → in_progress

A support agent picks up the ticket and begins investigation.

in_progress → waiting_customer

The support team has responded and needs additional information from you. Add a comment to move the ticket forward.

waiting_customer → in_progress

You replied with a comment — the ticket moves back to active investigation.

in_progress → on_hold

The issue requires external investigation (e.g., bank confirmation). The ticket is paused until the external party responds.

in_progress → resolved

The support team has resolved the issue. You can close the ticket or reopen it if the problem persists.

resolved → closed

You confirm the resolution by closing the ticket, or it is auto-closed after a period of inactivity.

resolved / closed → open (reopen)

You reopen the ticket via POST /tickets/:ticketId/reopen if the issue was not fully resolved.

Merchant-Allowed Transitions

As a merchant, you can perform these status transitions:

Action	Allowed From	Endpoint
Close	`open`, `in_progress`, `waiting_customer`, `resolved`	`POST /tickets/:ticketId/close`
Reopen	`resolved`, `closed`	`POST /tickets/:ticketId/reopen`

Category	Description
`payment_issue`	Problems with a specific payment (stuck, failed, wrong amount)
`integration`	API integration questions or issues
`limits`	Balance or transaction limit inquiries
`account`	Account settings, credentials, or access issues
`bug`	Bug reports for the API or dashboard
`question`	General questions
`dispute`	Payment dispute (replaces legacy appeals system)
`refund_request`	Request for a payment refund
`other`	Anything that doesn’t fit other categories

Webhook Events

When you have webhooks configured, the following ticket events are delivered:

Event	Trigger	Description
`ticket.created`	Ticket created via API	A new support ticket was created
`ticket.updated`	Ticket status changed	Ticket status was changed (e.g., reopened, moved to in_progress)
`ticket.comment_added`	Admin replies to your ticket	A public comment was added by the support team
`ticket.resolved`	Admin resolves ticket	Ticket was resolved by the support team
`ticket.closed`	Ticket closed	Ticket was closed (by merchant or support team)

ticket.comment_added fires only when the support team adds a public reply to your ticket. Internal notes are never delivered. For ticket.comment_added, the comment content is included in data.comment alongside data.ticket.

The webhook payload follows the same envelope structure as payment events, with the full ticket object in the data.ticket field:

{
  "id": "evt_tkt_abc123",
  "created_at": "2026-02-26T15:10:00Z",
  "merchant_id": "123",
  "data": {
    "ticket": {
      "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Payment stuck in pending",
      "description": "Payment pay_123456 has been pending for over 2 hours",
      "status": "open",
      "category": "payment_issue",
      "sub_category": null,
      "payment_id": "pay_123456",
      "transaction_id": null,
      "reference": null,
      "requires_refund": false,
      "resolution_summary": null,
      "attachments": [],
      "created_at": "2026-02-26T14:30:00.000Z",
      "updated_at": "2026-02-26T14:30:00.000Z",
      "resolved_at": null,
      "last_activity_at": "2026-02-26T14:30:00.000Z"
    }
  }
}

To receive ticket events, add them to your webhook subscription. See the Webhooks Guide for setup instructions.

Error Handling

All API responses use a unified envelope. On errors, success is false and the error field contains a human-readable message:

{
  "success": false,
  "error": "Invalid status transition: closed -> closed. Allowed source statuses: open, in_progress, waiting_customer, resolved",
  "statusCode": 400
}

Status Code	Meaning
`400`	Invalid request parameters or status transition
`401`	Unauthorized — missing or invalid API key
`404`	Ticket, comment, or attachment not found
`409`	Duplicate ticket for this payment ID

HTTP status is always 200. Check the success field and statusCode in the response body to determine the actual result.

Best Practices

Link Payments to Tickets

Always include payment_id or transaction_id when creating tickets about payment issues. This helps the support team investigate faster.

Use Correct Categories

Categorize tickets accurately. payment_issue and refund_request are auto-prioritized for faster resolution.

Add Context in Comments

When replying, include relevant details like timestamps, amounts, and error messages. Attach screenshots when possible.

Monitor via Webhooks

Subscribe to ticket.updated and ticket.comment_added events to get real-time notifications instead of polling the API.

Getting Started

Guides

SDKs & Examples

Reference

Support Tickets API

Support Tickets API

API Key Scopes

Creating a Ticket

Request Body

Response

Listing Tickets

Query Parameters

Response

Getting Ticket Details

Closing a Ticket

Reopening a Ticket

Comments

Adding a Comment

Comment Request Body

Listing Comments

Comment Response

Attachments

Supported File Types

Upload Workflow

Downloading Attachments

Ticket Statuses

Status Lifecycle

Merchant-Allowed Transitions

Categories

Webhook Events

Error Handling

Best Practices

Link Payments to Tickets

Use Correct Categories

Add Context in Comments

Monitor via Webhooks

Getting Started

Guides

SDKs & Examples

Reference

​Support Tickets API

​API Key Scopes

​Creating a Ticket

​Request Body

​Response

​Listing Tickets

​Query Parameters

​Response

​Getting Ticket Details

​Closing a Ticket

​Reopening a Ticket

​Comments

​Adding a Comment

​Comment Request Body

​Listing Comments

​Comment Response

​Attachments

​Supported File Types

​Upload Workflow

​Downloading Attachments

​Ticket Statuses

​Status Lifecycle

​Merchant-Allowed Transitions

​Categories

​Webhook Events

​Error Handling

​Best Practices

Link Payments to Tickets

Use Correct Categories

Add Context in Comments

Monitor via Webhooks

Support Tickets API

API Key Scopes

Creating a Ticket

Request Body

Response

Listing Tickets

Query Parameters

Response

Getting Ticket Details

Closing a Ticket

Reopening a Ticket

Comments

Adding a Comment

Comment Request Body

Listing Comments

Comment Response

Attachments

Supported File Types

Upload Workflow

Downloading Attachments

Ticket Statuses

Status Lifecycle

Merchant-Allowed Transitions

Categories

Webhook Events

Error Handling

Best Practices