The TicketService supports the full lifecycle of seller tickets. It enables you to perform read and write operations on tickets, specifically allowing you to:

• View your tickets
• Follow customer conversations
• Reply to customers and update ticket statuses
• Post private messages
• Request ticket topic changes
• Submit help requests to refurbed

All services and operations concerning tickets must be called with TicketService in the URL, followed by the command/operation.

https://api.refurbed.com/refb.merchant.v1.TicketService/ListTickets

All calls must be made using the POST method.

Create (CreateTicket / CreateTicketHelpRequest/ GenerateReturnShippingLabel)

Ticket Creation (CreateTicket)

Allows creation of a new ticket associated with a specific order item (marketplace or buyback). Tickets can be created by the customer or the seller. Each ticket requires a topic and an initial public message that is visible to all relevant parties. Attachments must be submitted with a filename and raw bytes (binary contents).

If the ticket is already in status CLOSED but you want to continue the conversation, please open a new ticket for the order item ID.

Ticket Topics

Every ticket must include a valid ticket topic. The topics are currently not exposed via Seller API. Here is the full list of ticket topic slugs you can use during the ticket creation:

• marketplace

  cancellation_supplier.pricing_error
  cancellation_supplier.stock_issue
  cancellation_supplier.customer_reasons
  cancellation_supplier.refurbed_error
  delivery.request_tracking_link
  delivery.change_delivery_address
  delivery.delivery_overdue
  delivery.lost_or_damaged_parcel
  delivery.lost_parcel
  delivery.damaged_parcel
  delivery.other
  refunds_repairs_exchanges.no_longer_need_the_product
  refunds_repairs_exchanges.expected_better_condition
  refunds_repairs_exchanges.expected_better_condition.display
  refunds_repairs_exchanges.expected_better_condition.frame
  refunds_repairs_exchanges.expected_better_condition.camera
  refunds_repairs_exchanges.expected_better_condition.dirt
  refunds_repairs_exchanges.expected_better_condition.keyboard
  refunds_repairs_exchanges.expected_better_condition.other
  refunds_repairs_exchanges.does_not_match_product_description
  refunds_repairs_exchanges.defective_product
  refunds_repairs_exchanges.defective_product.battery
  refunds_repairs_exchanges.defective_product.camera
  refunds_repairs_exchanges.defective_product.audio
  refunds_repairs_exchanges.defective_product.buttons
  refunds_repairs_exchanges.defective_product.keyboard
  refunds_repairs_exchanges.defective_product.network
  refunds_repairs_exchanges.defective_product.charger
  refunds_repairs_exchanges.defective_product.display
  refunds_repairs_exchanges.defective_product.software
  refunds_repairs_exchanges.defective_product.other
  refunds_repairs_exchanges.addon_defective
  refunds_repairs_exchanges.addon_does_not_fit_device
  refunds_repairs_exchanges.addon_quality_not_as_expected
  refunds_repairs_exchanges.other
  refund_request.no_longer_need_the_product
  refund_request.more_signs_of_usage_than_expected
  refund_request.more_signs_of_usage_than_expected.camera
  refund_request.more_signs_of_usage_than_expected.dirt
  refund_request.more_signs_of_usage_than_expected.display
  refund_request.more_signs_of_usage_than_expected.frame
  refund_request.more_signs_of_usage_than_expected.keyboard
  refund_request.more_signs_of_usage_than_expected.other
  refund_request.wrong_configuration_or_wrong_device
  refund_request.wrong_configuration_or_wrong_device.customer_ordered_wrong
  refund_request.wrong_configuration_or_wrong_device.supplier_sent_wrong
  refund_request.defective_product
  refund_request.defective_product.audio
  refund_request.defective_product.battery
  refund_request.defective_product.buttons
  refund_request.defective_product.camera
  refund_request.defective_product.charger
  refund_request.defective_product.display
  refund_request.defective_product.keyboard
  refund_request.defective_product.network
  refund_request.defective_product.software
  refund_request.defective_product.other
  refund_request.other
  repair_or_exchange_request.more_signs_of_usage_than_expected
  repair_or_exchange_request.more_signs_of_usage_than_expected.camera
  repair_or_exchange_request.more_signs_of_usage_than_expected.dirt
  repair_or_exchange_request.more_signs_of_usage_than_expected.display
  repair_or_exchange_request.more_signs_of_usage_than_expected.frame
  repair_or_exchange_request.more_signs_of_usage_than_expected.keyboard
  repair_or_exchange_request.more_signs_of_usage_than_expected.other
  repair_or_exchange_request.wrong_configuration_or_wrong_device
  repair_or_exchange_request.wrong_configuration_or_wrong_device.customer_ordered_wrong
  repair_or_exchange_request.wrong_configuration_or_wrong_device.supplier_sent_wrong
  repair_or_exchange_request.defective_product
  repair_or_exchange_request.defective_product.audio
  repair_or_exchange_request.defective_product.battery
  repair_or_exchange_request.defective_product.buttons
  repair_or_exchange_request.defective_product.camera
  repair_or_exchange_request.defective_product.charger
  repair_or_exchange_request.defective_product.display
  repair_or_exchange_request.defective_product.keyboard
  repair_or_exchange_request.defective_product.network
  repair_or_exchange_request.defective_product.software
  repair_or_exchange_request.defective_product.other
  repair_or_exchange_request.other
  refund_or_exchange_request
  refund_or_exchange_request.addon_defective
  refund_or_exchange_request.addon_does_not_fit_device
  refund_or_exchange_request.addon_does_not_match_product_description
  refund_or_exchange_request.no_longer_need_the_product
  refund_or_exchange_request.addon_quality_not_as_expected
  refund_or_exchange_request.other
  payment_and_invoices.request_invoice
  payment_and_invoices.invoice_issue_or_question
  payment_and_invoices.payment_issue
  payment_and_invoices.payment_questions
  payment_and_invoices.other
  other
  other_ticket_topic_change
  fashion.generic
  

• trade-in (buyback)

  buyback.generic
  

Ticket Status

Newly created tickets by the customer will be in status OPEN. A seller-created ticket will be in status PENDING. The following table shows the status a ticket can assume. Most of these are set automatically by our system via replying back and forth as well as timelines. If you want to mark a ticket for resolution, you can use the status SOLVED coming from OPEN or PENDING. SOLVED tickets can be reopened, CLOSED tickets need a follow-up ticket.

Below you see a typical status transition cycle:

Create Help Request (CreateTicketHelpRequest)

Creates a help request within an existing ticket to escalate or involve refurbed’s specialized support team, think of it as a side conversation. The original ticket_id and a topic must be specified to ensure correct routing, and an initial message (with optional attachments) is required to describe the issue. The help request is automatically created in the status OPEN. Once created, the help request becomes part of the ticket context while maintaining its own lifecycle.

Find all available help request topics in swagger.

ℹ️You can create only one help request per ticket and per topic.

Generate Return Label (GenerateReturnShippingLabel)

This endpoint generates a return shipping label, using the refurbed shipping agreement and makes it visible to the customer. A message will be automatically created containing the attachment for the ticket requestor, the ticket’s status will be set to PENDING automatically.

ℹ️The label URL is not disclosed in the response. If you want to get the return label URL, call OrderItemReturnService/ListOrderItemReturns or OrderService/GetOrder

⚠️GenerateReturnShippingLabel cannot be tested on our sandboxes, due to technical limitations.

Read (ListTickets / GetTicket / GetTicketHelpRequest / ListTicketHelpRequests)

List Tickets (ListTickets)

Lists all tickets with pagination. Tickets can be filtered by attributes such as ticket ID, assignee, status, customer details, order references (marketplace or buyback), market, topic, urgency status, and escalation indicators. Results support sorting and use cursor based pagination for efficient navigation.

By default, ListTickets only returns state and meta related ticket information, no message or message contents. To retrieve ticket messages, use GetTicket by providing the ticket_id for each individual ticket.

A separate ticket is created for each order item. For every ticket, we return the corresponding marketplace or buyback order item ID and order ID. You can use these IDs to retrieve the associated order details by calling OrderService/GetOrder or OrderItemService/GetOrderItem. For more information about orders, see: Orders

To stay within our rate limits and meet SLA requirements we recommend the following strategy:

• poll the ListTickets endpoint using seller_action_needed filter, follow up with GetTicket to receive the messages of these tickets.
• if needed, implement a separate polling logic with less high frequency for archived tickets (status: SOLVED and CLOSED)

⚠️For ListTickets please use a polling frequency of greater than 2 minutes, to reduce the risk of triggering your rate limits and use filter seller_action_needed: true to fetch only actionable tickets with GetTicket method. Make use of pagination and set it to 100 to return the maximum possible results.

Get Ticket Details (GetTicket)

Gets all details of a single ticket by providing the ticket_id, including its full message history as well as attachments.

SLA Checkpoints

Every time a ticket goes into state OPEN, sla_checkpoints will be populated and are intended to represent the active SLA timeline for the ticket. In particular, AWAITING_REPLY_SINCE, OVERDUE, and REFURBED_TAKEOVER are emitted from the current ticket SLA state, and when the underlying SLA fields are no longer present, the corresponding checkpoint is no longer returned.

ℹ️The timestamps and SLA values, we return, are not second-precise to the actual events happening in the conversation due to the synchronisation mechanism, but it is practically negligible.

sla_checkpoints will be removed from a ticket as soon as you send a response, customer_panicked is true or an urgency_status was set by refurbed.

Customer Panic

If a customer requests help from refurbed we will indicate this by customer_panicked turning to true in ListTickets and GetTicket responses. A refurbed agent will look at the ticket and decide the further course of action.

Urgency Status

Urgency status, or also referred to as health status, is a state set by refurbed’s Customer Service Team for tickets where the customer requests help from refurbed or where the SLAs are overdue. This field will only appear after refurbed has decided the further course of action and sent a message to the seller. The seller has 24 hours to respond to refurbed’s message, however it is not indicated by any sla_checkpoints or similar. Refurbed customer support will report manually in the ticket thread as soon as the timeline has passed.

Two values can be set for urgency_status:

List All Help Requests for a given Ticket (ListTicketHelpRequests)

Endpoint for fetching the list of help requests associated with a ticket.

To keep track of all your help request we recommend polling ListTickets with has_helprequests filter and then follow up with ListTicketHelpRequests. This methods returns the list of all help requests linked to a ticket. Get the help_request_id of the help request you want to view and then call GetTicketHelpRequest to fetch the help request’s details.

Below you see a typical status transition cycle:

Get Help Requests Details (GetTicketHelpRequest)

Provides visibility into a help request associated with a ticket, including its current status and a full message history to give complete context on the escalation and related communication.

Update (UpdateTicket / UpdateTicketHelpRequest / RequestTopicChange)

Ticket Updates (UpdateTicket)

After a ticket has been created, you can update it to manage ownership, progress its workflow, and communicate with the customer. The ticket is identified by its ticket_id.

This endpoint lets you add a new message to a ticket, either as a public reply to the customer or as an internal note for refurbed agents. Both message types support optional attachments. Internal messages are only visible to refurbed agents and are not shown to the seller.

Use new_message.scope to specify whether the message is PUBLIC or INTERNAL.

Sending either a public or an internal message automatically changes the ticket status to PENDING. If the issue has been resolved, set the ticket status to SOLVED when sending your reply to close the ticket.

You can also add an internal note that is only visible to your agents. Each ticket can have only one note. Adding a new note replaces the existing note.

In addition, this endpoint allows you to assign the ticket to a specific agent by specifying their user email address. You can only assign tickets to users existing in your refurbed account. You can add new users in your Seller Interface User Accounts.

Update Help Request (UpdateTicketHelpRequest)

When refurbed responds to your help request, they may either ask for additional information or resolve the request directly. As long as the help request is not in the CLOSED status, you can reply at any time to continue the conversation.

If refurbed requires additional information, the help request status is set to PENDING, indicating that a response from you is expected, before the request can be resolved.

The status is set to SOLVED, if refurbed resolves the request. If you have additional questions or need further clarification, you can reply with a new message to reopen the help request.

Whenever you reply to a help request, its status is automatically changed to OPEN, and refurbed will review your message.

Topic Change Requests (RequestTopicChange)

This method allows you to request a topic change for an existing ticket.

Check if a ticket topic change is allowed for the ticket in question by calling ListTickets or GetTicket. If topic_change_allowed is set to true then you can proceed and request a topic change.

To request a ticket topic change, you need to provide the ticket ID and a message. In most cases, also attachments are necessary. Follow our ticket topic changes guidelines to verify the documentation requirements for each product category. In some cases, you can request a topic change without documentation, in those cases, you need to provide the attachment_exemption_reason. Available values can be found in swagger. Please refer to the guidelines to identify applicable scenarios.

If your ticket topic change request does not meet our criteria, then we’ll directly return an error message when you call RequestTopicChange.

Otherwise, your topic change request is reviewed by our Seller Performance Team. If it is accepted, the ticket topic will be updated to other_ticket_topic_change.