> For the complete documentation index, see [llms.txt](https://parcelwill-returns.gitbook.io/help-center/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://parcelwill-returns.gitbook.io/help-center/openapi/overview.md).

# Overview

### Overview

Return OpenAPI is used by merchant-side systems to send return label data back to Return after receiving a return webhook.

Typical flow:

1. Return sends a webhook to the merchant system.
2. The merchant system reads `rma`, return items, customer address, product weight, and HS code from the webhook payload.
3. The merchant system creates a return label in its own WMS, TMS, or carrier system.
4. The merchant system calls `POST /open-api/v1/return-labels` to send the label back to Return.
5. Return processes the label according to the current return request status.

### API Base URL

The final host is provided by Return.

```
https://return-go-api.parcelwill.com
```

Examples in this document use:

```
$BASE_URL/open-api/v1
```

### Authentication

All OpenAPI requests require a shop domain and access token.

| Header                  | Required | Description                                           |
| ----------------------- | -------- | ----------------------------------------------------- |
| `X-RETURN-SHOP-DOMAIN`  | Yes      | Shopify shop domain, for example `demo.myshopify.com` |
| `X-RETURN-ACCESS-TOKEN` | Yes      | Webhook token provided by Return                      |

You can also pass the token with `Authorization`:

```http
Authorization: Bearer <token>
```

Example:

```bash
curl "$BASE_URL/open-api/v1/return-addresses" \
  -H "X-RETURN-SHOP-DOMAIN: demo.myshopify.com" \
  -H "X-RETURN-ACCESS-TOKEN: your-token"
```

### Available APIs

| Page                    | Method | Path                            | Description                                            |
| ----------------------- | ------ | ------------------------------- | ------------------------------------------------------ |
| Create Return Label     | `POST` | `/open-api/v1/return-labels`    | Send merchant-created return label data back to Return |
| Get Return Request List | `GET`  | `/open-api/v1/return-requests`  | Page through return requests for the current shop      |
| Get Return Addresses    | `GET`  | `/open-api/v1/return-addresses` | Get available return addresses for `return_address_id` |

### Common Response Format

Success:

```json
{
  "code": 1000,
  "msg": "success",
  "data": {}
}
```

Error:

```json
{
  "code": 1002,
  "msg": "tracking_number and shipping_carrier are required",
  "data": null
}
```

### Important Notes

* Label upload uses `rma` to identify the return request.
* `request_id` is returned in some responses for reference, but merchants do not need it to upload labels.
* Request signing is not required for OpenAPI.
* The token must be stored server-side only.
* Do not expose the token in browser code, mobile apps, public repositories, or public logs.