English

简体中文

English

简体中文

About Refund ​

Access scope

Multiple access scopes needed — refer to each endpoint for access scope requirements.

Refund Management is a crucial component of the Genstore trading system, offering standardized refund processing workflows and management capabilities. Through standardized refund handling mechanisms, it helps merchants efficiently process various refund scenarios and improve after-sales service quality.

Core Features

  • Create Refund: Create refund request, specify refund amount, set refund reason and method.
  • Manage Refund Status: Update refund status, track refund progress.
  • Query Refund Information: Get refund details, list refund orders, query order-related refunds.

Use Cases

  • After-sales Refund Processing: Customer service teams can quickly respond to refund applications, track refund progress, and maintain refund records to ensure efficient after-sales service experience.
  • Refund Risk Management: Risk control teams can review abnormal refunds, monitor refund trends, and identify fraud risks to ensure transaction security.
  • Financial Reconciliation: Finance teams can analyze refund data, verify refund details, and generate reconciliation reports to achieve accurate financial management.
  • Business Analysis: Operations teams can analyze refund reasons, evaluate service quality, and optimize product strategies to improve operational efficiency.

Endpoints

POST /api/202412/refunds: Create after-sales record

PUT /api/202412/refunds/{refundId}: Review after-sales status

GET /api/202412/orders/{orderId}/refunds: Get order after-sales list

GET /api/202412/refunds?orderId={orderId}&refundId={refundId}: Get after-sale detail

The Refund resource Object ​

The Refund resource

Properties ​

refundobjectrequired
Information about the after-sale.
- Hide child properties
refundIdnumberrequired
This is a after-sale number.
customerIdnumberrequired
Customer unique identification.
lineItemsarrayrequired
A list of after-sale line items. Each entry has the following properties:
+ Show child properties
notestringrequired
An optional note attached to a after-sale.
createTimestringrequired
The date and time (ISO 8601 format) when the refund was created.
updateTimestringrequired
The date and time (ISO 8601 format) when the refund was update.
refundPricenumberrequired
This is the refund amount.
statusnumberrequired
Status of the after-sales order. Enum values: 1. After-sales initiated 2. In process 3. Completed 4. Canceled 5. Abnormal status
bash
{
  "refund": {
    "lineItems": [
      {
        "totalTax": "0.00",
        "lineItem": {
          "productId": "123",
          "variantId": "222"
        },
        "quantity": "",
        "lineItemId": "",
        "subtotal": "10.00"
      }
    ],
    "note": "Note",
    "createTime": "2013-06-27T08:48:27-04:00",
    "customerId": "1020000013594",
    "updateTime": "2012-08-24T14:01:46-04:00",
    "refundPrice": "10.00",
    "refundId": "1000069823694",
    "status": ""
  }
}

POST Create after-sales record ​

Create after-sales record

Access scope

Requires ANY of the following access scopes: write_refunds

Endpoint

POST /api/202412/refunds 

Request Params

refundobjectrequired
Information about the refund.
- Hide child properties
requestNostringrequired
Create an idempotent key for the record to prevent duplicate creation. The length should not exceed 50 characters and must be at least 20 characters.
customerIdnumber
Customer unique identification.
lineItemsarrayrequired
A list of refunded line items. Each entry has the following properties:
+ Show child properties
notestringrequired
An optional note attached to a refund.
orderIdnumberrequired
Order number for creating after-sales records.
rightsTypenumber
After-sales types 1: Return and refund(default) 2: Refund

Response Data

refundobjectrequired
Information about the refund.
- Hide child properties
refundIdnumberrequired
This is a refund order number.
customerIdnumberrequired
Customer unique identification.
lineItemsarrayrequired
A list of refunded line items. Each entry has the following properties:
+ Show child properties
notestringrequired
An optional note attached to a refund.
createTimestringrequired
The date and time (ISO 8601 format) when the refund was created.
updateTimestringrequired
The date and time (ISO 8601 format) when the refund was update.
orderIdnumberrequired
Order number for creating after-sales records.
statusnumberrequired
Status of the after-sales order. Enum values: 1. After-sales initiated 2. In process 3. Completed 4. Canceled 5. Abnormal status
rightsTypenumberrequired
After-sales types 1: Return and refund 2: Refund
bash
curl -X POST \ 
https://{shop}.genmystore.com/api/202412/refunds" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"refund":{
		"lineItems":[
			{
				"quantity":"12",
				"lineItemId":"128323456"
			}
		],
		"note":"Item was damaged during shipping",
		"rightsType":"1",
		"orderId":"",
		"customerId":"238478920",
		"requestNo":"asdfaddsadafd"
	}
}'
json
HTTP/1.1 200 OK
{
  "refund": {
    "lineItems": [
      {
        "totalTax": "0.00",
        "lineItem": {
          "productId": "123",
          "variantId": "222"
        },
        "quantity": "12",
        "lineItemId": "128323456",
        "subtotal": "1"
      }
    ],
    "note": "Item was damaged during shipping",
    "rightsType": "1",
    "createTime": "2008-01-10T11:00:00-05:00",
    "orderId": "",
    "customerId": "238478920",
    "updateTime": "2008-01-10T11:00:00-05:00",
    "refundId": "255858046",
    "status": ""
  }
}

PUT Review after-sales status ​

Review after-sales status。

Access scope

Requires ANY of the following access scopes: write_refunds

Endpoint

PUT /api/202412/refunds/{refundId} 

Request Params

orderIdnumberrequired
The order's position in the shop's count of orders.
refundIdnumberrequired
This is a refund order number.
actionnumberrequired
Review status. The enumeration values are as follows: 1: Approved, final refund action will be taken 2: Rejected, the order status will change to cancelled.

Response Data

refundobjectrequired
Information about the refund.
- Hide child properties
refundIdnumberrequired
This is a refund order number.
lineItemsarrayrequired
A list of refunded line items. Each entry has the following properties:
+ Show child properties
notestringrequired
An optional note attached to a refund.
createTimestringrequired
The date and time (ISO 8601 format) when the refund was created.
updateTimestringrequired
The date and time (ISO 8601 format) when the refund was update.
statusnumberrequired
Status of the after-sales order. Enum values: 1. After-sales initiated 2. In process 3. Completed 4. Canceled 5. Abnormal status
customerIdnumberrequired
Customer unique identification.
rightsTypenumberrequired
After-sales types 1: Return and refund 2: Refund
bash
curl -X PUT \ 
https://{shop}.genmystore.com/api/202412/refunds/{refundId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"orderId":"39072856",
	"action":"1",
	"refundId":"255858046"
}'
json
HTTP/1.1 200 OK
{
  "refund": {
    "lineItems": [
      {
        "totalTax": "0.00",
        "lineItem": {
          "productId": "123",
          "variantId": "222"
        },
        "quantity": "12",
        "lineItemId": "128323456",
        "subtotal": "1"
      }
    ],
    "note": "Item was damaged during shipping",
    "rightsType": "1",
    "createTime": "2008-01-10T11:00:00-05:00",
    "customerId": "238478920",
    "updateTime": "2008-01-10T11:00:00-05:00",
    "refundId": "255858046",
    "status": "1"
  }
}

GET Get order after-sales list ​

Inquire about after-sales information based on the order.

Access scope

Requires ANY of the following access scopes: read_refunds

Endpoint

GET /api/202412/orders/{orderId}/refunds 

Request Params

orderIdnumberrequired
The order's position in the shop's count of orders.
limitnumberrequired
Define the number of records per page, with a default of 50 and a maximum of 250.

Response Data

refundsarrayrequired
Information about the refund.
- Hide child properties
refundIdnumberrequired
This is a refund order number.
customerIdnumberrequired
Customer unique identification.
lineItemsarrayrequired
A list of refunded line items. Each entry has the following properties:
+ Show child properties
notestringrequired
An optional note attached to a refund.
createTimestringrequired
The date and time (ISO 8601 format) when the refund was created.
updateTimestringrequired
The date and time (ISO 8601 format) when the refund was update.
statusnumberrequired
Status of the after-sales order. Enum values: 1. After-sales initiated 2. In process 3. Completed 4. Canceled 5. Abnormal status
rightsTypenumberrequired
After-sales types 1: Return and refund 2: Refund
bash
curl -X GET \ 
https://{shop}.genmystore.com/api/202412/orders/{orderId}/refunds" \ 
-H "X-Genstore-Access-Token: {access_token}" \
json
HTTP/1.1 200 OK
{
  "refunds": [
    {
      "lineItems": [
        {
          "totalTax": "0.00",
          "lineItem": {
            "productId": "123",
            "variantId": "222"
          },
          "quantity": "12",
          "lineItemId": "128323456",
          "subtotal": "1"
        }
      ],
      "note": "Item was damaged during shipping",
      "rightsType": "1",
      "createTime": "2008-01-10T11:00:00-05:00",
      "customerId": "238478920",
      "updateTime": "2008-01-10T11:00:00-05:00",
      "refundId": "255858046",
      "status": ""
    }
  ]
}

GET Get after-sale detail ​

Get details of a specific after-sale record.

Access scope

Requires ANY of the following access scopes: read_refunds

Endpoint

GET /api/202412/refunds?orderId={orderId}&refundId={refundId} 

Request Params

orderIdnumberrequired
The order's position in the shop's count of orders.
refundIdnumberrequired
Collection of refund order numbers

Response Data

refundobjectrequired
Information about the after-sale record.
- Hide child properties
refundIdnumberrequired
This is a after-sale number.
customerIdnumberrequired
Customer unique identification.
lineItemsarrayrequired
A list of refunded line items. Each entry has the following properties:
+ Show child properties
notestringrequired
An optional note attached to a refund.
createTimestringrequired
The date and time (ISO 8601 format) when the refund was created.
updateTimestringrequired
The date and time (ISO 8601 format) when the refund was update.
statusnumberrequired
Status of the after-sales order. Enum values: 1. After-sales initiated 2. In process 3. Completed 4. Canceled 5. Abnormal status
rightsTypenumberrequired
After-sales types 1: Return and refund 2: Refund
bash
curl -X GET \ 
https://{shop}.genmystore.com/api/202412/refunds?orderId={orderId}&refundId={refundId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \
json
HTTP/1.1 200 OK
{
  "refund": {
    "lineItems": [
      {
        "totalTax": "0.00",
        "lineItem": {
          "productId": "123",
          "variantId": "222"
        },
        "quantity": "12",
        "lineItemId": "128323456",
        "subtotal": "1"
      }
    ],
    "note": "Item was damaged during shipping",
    "rightsType": "1",
    "createTime": "2008-01-10T11:00:00-05:00",
    "customerId": "238478920",
    "updateTime": "2008-01-10T11:00:00-05:00",
    "refundId": "255858046",
    "status": "1"
  }
}