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 refund

PUT /api/202412/refunds/{refundId}: Update refund status

GET /api/202412/refunds?ids={refundIds}: Get refund details

GET /api/202412/orders/{orderId}/refunds: Get order refund list

The Refund resource Object

The Refund resource

Properties

refundobject

Information about the refund.

- Hide child properties

idnumber

This is a refund order number.

customerIdnumber

Customer unique identification.

customerobject

Information about the customer.

+ Show child properties

lineItemsarray

A list of refunded line items. Each entry has the following properties:

+ Show child properties

notestring

An optional note attached to a refund.

createTimestring

The date and time (ISO 8601 format) when the refund was created.

updateTimestring

The date and time (ISO 8601 format) when the refund was update.

refundPricenumber

This is the requested refund amount.

The Refund resource Object

{
  "refund": {
    "lineItems": [
      {
        "line_item": "",
        "line_item_id": "",
        "quantity": "",
        "subtotal": "10.00",
        "id": "",
        "total_tax": "0.00",
        "location_id": ""
      }
    ],
    "note": "Note",
    "createTime": "2013-06-27T08:48:27-04:00",
    "customerId": "1020000013594",
    "updateTime": "2012-08-24T14:01:46-04:00",
    "id": "1000069823694",
    "refundPrice": "10.00",
    "customer": {
      "lastName": "Terry",
      "note": "This is Note.",
      "updatedTime": "2012-08-24T14:01:46-04:00",
      "addresses": "",
      "taxExempt": "",
      "taxExemptions": "",
      "tags": "",
      "firstName": "",
      "phone": "",
      "createdTime": "2013-06-27T08:48:27-04:00",
      "currency": "",
      "id": "",
      "state": "",
      "email": "",
      "verifiedEmail": "",
      "defaultAddress": ""
    }
  }
}

POST Create refund

Create a refund.

Access scope

Requires ANY of the following access scopes: write_refunds

Endpoint

POST /api/202412/refunds 

Request Params

refundobject

Information about the refund.

- Hide child properties

refundIdnumber

This is a refund order number.

customerIdnumber

Customer unique identification.

customerobject

Information about the customer.

+ Show child properties

lineItemsarray

A list of refunded line items. Each entry has the following properties:

+ Show child properties

notestring

An optional note attached to a refund.

createTimestring

The date and time (ISO 8601 format) when the refund was created.

updateTimestring

The date and time (ISO 8601 format) when the refund was update.

Response Data

refundobject

Information about the refund.

- Hide child properties

refundIdnumber

This is a refund order number.

customerIdnumber

Customer unique identification.

customerobject

Information about the customer.

+ Show child properties

lineItemsarray

A list of refunded line items. Each entry has the following properties:

+ Show child properties

notestring

An optional note attached to a refund.

createTimestring

The date and time (ISO 8601 format) when the refund was created.

updateTimestring

The date and time (ISO 8601 format) when the refund was update.

POST /api/202412/refunds

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":[
			{
				"line_item":"{}",
				"line_item_id":"128323456",
				"quantity":"12",
				"subtotal":"1",
				"id":"209341123",
				"total_tax":"0.00",
				"location_id":"40642626"
			}
		],
		"note":"Item was damaged during shipping",
		"createTime":"2008-01-10T11:00:00-05:00",
		"customerId":"238478920",
		"updateTime":"2008-01-10T11:00:00-05:00",
		"refundId":"255858046",
		"customer":{
			"lastName":"John",
			"note":"A note about the customer.",
			"addresses":"address",
			"taxExempt":"true",
			"taxExemptions":"[\"CA_STATUS_CARD_EXEMPTION\",\"CA_BC_RESELLER_EXEMPTION\"]",
			"tags":"black",
			"createdAt":"2013-06-27T08:48:27-04:00",
			"firstName":"Norman",
			"phone":"16135551111",
			"currency":"JPY",
			"id":"207119551",
			"state":"disabled",
			"email":"[email protected]",
			"updatedAt":"2012-08-24T14:01:46-04:00",
			"verifiedEmail":"true",
			"defaultAddress":"11"
		}
	}
}'

Response

HTTP/1.1 200 OK
{
  "refund": {
    "lineItems": [
      {
        "line_item": "{}",
        "line_item_id": "128323456",
        "quantity": "12",
        "subtotal": "1",
        "id": "209341123",
        "total_tax": "0.00",
        "location_id": "40642626"
      }
    ],
    "note": "Item was damaged during shipping",
    "createTime": "2008-01-10T11:00:00-05:00",
    "customerId": "238478920",
    "updateTime": "2008-01-10T11:00:00-05:00",
    "refundId": "255858046",
    "customer": {
      "lastName": "John",
      "note": "A note about the customer.",
      "addresses": "address",
      "taxExempt": "true",
      "taxExemptions": "[\"CA_STATUS_CARD_EXEMPTION\",\"CA_BC_RESELLER_EXEMPTION\"]",
      "tags": "black",
      "createdAt": "2013-06-27T08:48:27-04:00",
      "firstName": "Norman",
      "phone": "16135551111",
      "currency": "JPY",
      "id": "207119551",
      "state": "disabled",
      "email": "[email protected]",
      "updatedAt": "2012-08-24T14:01:46-04:00",
      "verifiedEmail": "true",
      "defaultAddress": "111"
    }
  }
}

PUT Update refund status

Update refund status.

Access scope

Requires ANY of the following access scopes: write_refunds

Endpoint

PUT /api/202412/refunds/{refundId} 

Request Params

orderIdstring

The order's position in the shop's count of orders.

refundIdstring

This is a refund order number.

statusnumber

This is a refund status

Response Data

refundobject

Information about the refund.

- Hide child properties

refundIdnumber

This is a refund order number.

customerIdnumber

Customer unique identification.

customerobject

Information about the customer.

+ Show child properties

lineItemsarray

A list of refunded line items. Each entry has the following properties:

+ Show child properties

notestring

An optional note attached to a refund.

createTimestring

The date and time (ISO 8601 format) when the refund was created.

updateTimestring

The date and time (ISO 8601 format) when the refund was update.

PUT /api/202412/refunds/{refundId}

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",
	"refundId":"255858046",
	"status":"1"
}'

Response

HTTP/1.1 200 OK
{
  "refund": {
    "lineItems": [
      {
        "line_item": "{}",
        "line_item_id": "128323456",
        "quantity": "12",
        "subtotal": "1",
        "id": "209341123",
        "total_tax": "0.00",
        "location_id": "40642626"
      }
    ],
    "note": "Item was damaged during shipping",
    "createTime": "2008-01-10T11:00:00-05:00",
    "customerId": "238478920",
    "updateTime": "2008-01-10T11:00:00-05:00",
    "refundId": "255858046",
    "customer": {
      "lastName": "John",
      "note": "A note about the customer.",
      "addresses": "address",
      "taxExempt": "true",
      "taxExemptions": "[\"CA_STATUS_CARD_EXEMPTION\",\"CA_BC_RESELLER_EXEMPTION\"]",
      "tags": "black",
      "createdAt": "2013-06-27T08:48:27-04:00",
      "firstName": "Norman",
      "phone": "16135551111",
      "currency": "JPY",
      "id": "207119551",
      "state": "disabled",
      "email": "[email protected]",
      "updatedAt": "2012-08-24T14:01:46-04:00",
      "verifiedEmail": "true",
      "defaultAddress": "111"
    }
  }
}

GET Get refund details

Get details of a specific refund.

Access scope

Requires ANY of the following access scopes: write_refunds read_refunds

Endpoint

GET /api/202412/refunds?ids={refundIds} 

Request Params

orderIdnumber

The order's position in the shop's count of orders.

fieldsobject

Show only certain fields, specified by a comma-separated list of field names.

refundIdsarray

Collection of refund order numbers

Response Data

refundobject

Information about the refund.

- Hide child properties

refundIdnumber

This is a refund order number.

customerIdnumber

Customer unique identification.

customerobject

Information about the customer.

+ Show child properties

lineItemsarray

A list of refunded line items. Each entry has the following properties:

+ Show child properties

notestring

An optional note attached to a refund.

createTimestring

The date and time (ISO 8601 format) when the refund was created.

updateTimestring

The date and time (ISO 8601 format) when the refund was update.

GET /api/202412/refunds?ids={refundIds}

curl -X GET \ 
https://{shop}.genmystore.com/api/202412/refunds?ids={refundIds}" \ 
-H "X-Genstore-Access-Token: {access_token}" \

Response

HTTP/1.1 200 OK
{
  "refund": {
    "lineItems": [
      {
        "line_item": "{}",
        "line_item_id": "128323456",
        "quantity": "12",
        "subtotal": "1",
        "id": "209341123",
        "total_tax": "0.00",
        "location_id": "40642626"
      }
    ],
    "note": "Item was damaged during shipping",
    "createTime": "2008-01-10T11:00:00-05:00",
    "customerId": "238478920",
    "updateTime": "2008-01-10T11:00:00-05:00",
    "refundId": "255858046",
    "customer": {
      "lastName": "John",
      "note": "A note about the customer.",
      "addresses": "address",
      "taxExempt": "true",
      "taxExemptions": "[\"CA_STATUS_CARD_EXEMPTION\",\"CA_BC_RESELLER_EXEMPTION\"]",
      "tags": "black",
      "createdAt": "2013-06-27T08:48:27-04:00",
      "firstName": "Norman",
      "phone": "16135551111",
      "currency": "JPY",
      "id": "207119551",
      "state": "disabled",
      "email": "[email protected]",
      "updatedAt": "2012-08-24T14:01:46-04:00",
      "verifiedEmail": "true",
      "defaultAddress": "111"
    }
  }
}

GET Get order refund list

Get a list of refunded orders.

Access scope

Requires ANY of the following access scopes: write_refunds read_refunds

Endpoint

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

Request Params

orderIdnumber

The order's position in the shop's count of orders.

limitnumber

Define the number of records per page, with a default of 50 and a maximum of 250.

fieldsobject

Show only certain fields, specified by a comma-separated list of field names.

Response Data

refundsarray

Information about the refund.

- Hide child properties

refundIdnumber

This is a refund order number.

customerIdnumber

Customer unique identification.

customerobject

Information about the customer.

+ Show child properties

lineItemsarray

A list of refunded line items. Each entry has the following properties:

+ Show child properties

notestring

An optional note attached to a refund.

createTimestring

The date and time (ISO 8601 format) when the refund was created.

updateTimestring

The date and time (ISO 8601 format) when the refund was update.

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

curl -X GET \ 
https://{shop}.genmystore.com/api/202412/orders/{orderId}/refunds" \ 
-H "X-Genstore-Access-Token: {access_token}" \

Response

HTTP/1.1 200 OK
{
  "refunds": [
    {
      "lineItems": [
        {
          "line_item": "{}",
          "line_item_id": "128323456",
          "quantity": "12",
          "subtotal": "1",
          "id": "209341123",
          "total_tax": "0.00",
          "location_id": "40642626"
        }
      ],
      "note": "Item was damaged during shipping",
      "createTime": "2008-01-10T11:00:00-05:00",
      "customerId": "238478920",
      "updateTime": "2008-01-10T11:00:00-05:00",
      "refundId": "255858046",
      "customer": {
        "lastName": "John",
        "note": "A note about the customer.",
        "addresses": "address",
        "taxExempt": "true",
        "taxExemptions": "[\"CA_STATUS_CARD_EXEMPTION\",\"CA_BC_RESELLER_EXEMPTION\"]",
        "tags": "Norman",
        "createdAt": "2013-06-27T08:48:27-04:00",
        "firstName": "Norman",
        "phone": "16135551111",
        "currency": "JPY",
        "id": "207119551",
        "state": "disabled",
        "email": "[email protected]",
        "updatedAt": "2012-08-24T14:01:46-04:00",
        "verifiedEmail": "true",
        "defaultAddress": "defaultAddress"
      }
    }
  ]
}

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.

The Refund resource Object

The Refund resource

Properties

POST Create refund

Create a refund.

Access scope

Requires ANY of the following access scopes: write_refunds

Endpoint

POST /api/202412/refunds 

PUT Update refund status

Update refund status.

Access scope

Requires ANY of the following access scopes: write_refunds

Endpoint

PUT /api/202412/refunds/{refundId} 

GET Get refund details

Get details of a specific refund.

Access scope

Requires ANY of the following access scopes: write_refunds read_refunds

Endpoint

GET /api/202412/refunds?ids={refundIds} 

GET Get order refund list

Get a list of refunded orders.

Access scope

Requires ANY of the following access scopes: write_refunds read_refunds

Endpoint

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