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_sk_your_key_id:your_secret" \
  -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
  }'

import requests

ticket = requests.post(
    "https://api.lux-core.io/api/v1/tickets",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "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,
    },
)
print(ticket.json())

const response = await fetch("https://api.lux-core.io/api/v1/tickets", {
  method: "POST",
  headers: {
    "X-API-Key": "qp_test_sk_your_key_id:your_secret",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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,
  }),
});
const ticket = await response.json();
console.log(ticket);

Request Body

Field	Type	Required	Description
`title`	string	Yes	Ticket title (max 200 characters)
`priority`	string	No	`low`, `medium` or `high`; default `medium`
`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 an error result with code 409 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_sk_your_key_id:your_secret"

import requests

tickets = requests.get(
    "https://api.lux-core.io/api/v1/tickets",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    params={
        "status": "open",
        "sort_by": "created_at",
        "sort_order": "desc",
        "limit": 20,
    },
)
print(tickets.json())

const params = new URLSearchParams({
  status: "open",
  sort_by: "created_at",
  sort_order: "desc",
  limit: "20",
});
const response = await fetch(
  `https://api.lux-core.io/api/v1/tickets?${params}`,
  { headers: { "X-API-Key": "qp_test_sk_your_key_id:your_secret" } },
);
const tickets = await response.json();
console.log(tickets);

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_sk_your_key_id:your_secret"

ticket = requests.get(
    "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
)
print(ticket.json())

const response = await fetch(
  "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  { headers: { "X-API-Key": "qp_test_sk_your_key_id:your_secret" } },
);
const ticket = await response.json();
console.log(ticket);

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_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Issue resolved, closing ticket"
  }'

result = requests.post(
    "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/close",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={"comment": "Issue resolved, closing ticket"},
)
print(result.json())

const response = await fetch(
  "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/close",
  {
    method: "POST",
    headers: {
      "X-API-Key": "qp_test_sk_your_key_id:your_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ comment: "Issue resolved, closing ticket" }),
  },
);
const result = await response.json();
console.log(result);

Close is allowed from open, in_progress, waiting_customer, on_hold or resolved. Inspect the returned success flag; an invalid transition returns code 409 in the error result.

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_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Issue persists, reopening"
  }'

result = requests.post(
    "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reopen",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={"comment": "Issue persists, reopening"},
)
print(result.json())

const response = await fetch(
  "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reopen",
  {
    method: "POST",
    headers: {
      "X-API-Key": "qp_test_sk_your_key_id:your_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ comment: "Issue persists, reopening" }),
  },
);
const result = await response.json();
console.log(result);

Comments

Comments cannot be added to tickets in a final status. An invalid status transition can return code 409 in the error result; check both the HTTP status and body success before retrying.

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_sk_your_key_id:your_secret" \
  -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"
      }
    ]
  }'

result = requests.post(
    "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "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",
            }
        ],
    },
)
print(result.json())

const response = await fetch(
  "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments",
  {
    method: "POST",
    headers: {
      "X-API-Key": "qp_test_sk_your_key_id:your_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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",
        },
      ],
    }),
  },
);
const result = await response.json();
console.log(result);

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_sk_your_key_id:your_secret"

comments = requests.get(
    "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    params={"limit": 50, "offset": 0},
)
print(comments.json())

const response = await fetch(
  "https://api.lux-core.io/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments?limit=50&offset=0",
  { headers: { "X-API-Key": "qp_test_sk_your_key_id:your_secret" } },
);
const comments = await response.json();
console.log(comments);

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
  }
}

The API returns comments published to your ticket.

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_sk_your_key_id:your_secret" \
  -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_sk_your_key_id:your_secret"

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_sk_your_key_id:your_secret"

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

Adding a comment updates the ticket conversation; it does not itself change the ticket status.

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.

resolved / closed / canceled → 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`, `on_hold`, `resolved`	`POST /tickets/:ticketId/close`
Reopen	`resolved`, `closed`, `canceled`	`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`	A comment is published to your ticket	A comment was added to the ticket
`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 notifies you of a comment published to your ticket, including merchant comments. 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

Check both HTTP status and the response body. Request/authentication failures use the standard statusCode, message, error_code format. Ticket business failures can return success: false, error and statusCode even with an HTTP success status; do not treat HTTP 200/201 alone as completion. A ticket business-error result can look like this:

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

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

Ticket creation and comment creation return HTTP 201 Created. Other successful operations return HTTP 200 OK. Check the success field and statusCode in the response body for error details.

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

Choose an accurate category and set the appropriate priority when creating a ticket.

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

​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