shopee

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 25, 2026 License: MIT Imports: 13 Imported by: 0

README

go-shopee

Go Reference CI Go Report Card codecov

A small, dependency-free Go client for the Shopee Open Platform v2 API — the seller / shop API documented at open.shopee.com/developer-guide.

It handles the fiddly parts (v2 HMAC-SHA256 request signing, the OAuth token flow, regional hosts) so you can call shop / order / product endpoints with typed Go methods. Standard library only — no third-party dependencies.

This is the Open Platform (seller) API, not the Shopee Affiliate API.

Install

go get github.com/ultramcu/go-shopee

Requires Go 1.21+.

Quick start

package main

import (
	"context"
	"fmt"
	"log"

	shopee "github.com/ultramcu/go-shopee"
)

func main() {
	c := shopee.NewClient(shopee.Config{
		PartnerID:  10001,
		PartnerKey: "your-partner-key",
		Region:     shopee.RegionGlobal, // or RegionSandbox for testing
	})
	ctx := context.Background()

	// 1. Send the seller to the authorization URL. Shopee redirects them back
	//    to your callback with ?code=...&shop_id=...
	fmt.Println(c.AuthURL("https://your.app/shopee/callback"))

	// 2. Exchange the code for tokens (stored on the client on success).
	if _, err := c.GetAccessToken(ctx, codeFromCallback, shopID); err != nil {
		log.Fatal(err)
	}

	// 3. Call shop-scoped APIs.
	info, err := c.GetShopInfo(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(info.ShopName, info.Region)
}

Already have tokens? Skip the OAuth steps and set them directly:

c := shopee.NewClient(shopee.Config{
	PartnerID:   10001,
	PartnerKey:  "your-partner-key",
	Region:      shopee.RegionGlobal,
	ShopID:      123456,
	AccessToken: "access-token",
})

Refresh before the access token expires:

tok, err := c.RefreshAccessToken(ctx, refreshToken, shopID)

Signing

The v2 signature is computed and attached automatically on every call. For reference, the signed base string is:

  • Public APIs: partner_id + api_path + timestamp
  • Shop APIs: partner_id + api_path + timestamp + access_token + shop_id

then sign = hex(HMAC-SHA256(base, partner_key)), sent alongside partner_id, timestamp (and access_token + shop_id for shop APIs). The formula is pinned by a unit test, and the test suite verifies the exact sign reaches the server end-to-end.

Supported endpoints

Area Methods
Auth AuthURL, GetAccessToken, RefreshAccessToken
Shop GetShopInfo
Order GetOrderList, GetOrderDetail, CancelOrder, HandleBuyerCancellation, SetNote, GetBuyerInvoiceInfo
Shipping GetShippingParameter, ShipOrder, GetTrackingNumber, GetShipmentList
Logistics GetChannelList, GetAddressList, GetTrackingInfo, GetShippingDocumentParameter, CreateShippingDocument, GetShippingDocumentResult, DownloadShippingDocument, GetMassShippingParameter
Product — read GetItemList, GetItemBaseInfo, GetItemExtraInfo, GetModelList
Product — write AddItem, UpdateItem, DeleteItem, UnlistItem, UpdateStock, UpdatePrice
Product — variations InitTierVariation, UpdateTierVariation, AddModel, UpdateModel, DeleteModel
Product — catalog GetCategory, GetAttributes, GetBrandList, CategoryRecommend, GetItemLimit
Payment GetEscrowDetail, GetEscrowList, GetPayoutDetail, GetWalletTransactionList, GetPaymentMethodList
Returns GetReturnList, GetReturnDetail, ConfirmReturn, DisputeReturn, QueryReturnProof

This covers the core seller workflow — auth, shop, orders, shipping/logistics, products (read + write + variations + catalog), payment and returns. Remaining modules (discount, voucher, media upload, push/webhooks, merchant, marketing, …) are tracked in the issues; each is a thin typed wrapper over the signed request layer. Contributions welcome.

Regions

Region selects the host: RegionGlobal (live), RegionSandbox (global test), RegionChina, RegionChinaSandbox. Use Config.BaseURL to point at any other host (or a test server).

Errors

A non-empty API error envelope is returned as an *APIError (Err, Message, RequestID); use errors.As. Transport / decoding problems are returned as ordinary wrapped errors.

License

MIT — SPDX-License-Identifier: MIT.

Documentation

Overview

Package shopee is a small, dependency-free Go client for the Shopee Open Platform v2 API — the seller / shop API documented at https://open.shopee.com/developer-guide.

It handles v2 request signing (HMAC-SHA256), the OAuth token flow (authorize → code → access / refresh token), regional hosts (global, China, and their sandboxes), and a focused set of shop, order and product endpoints. The transport is the Go standard library only — no third-party dependencies.

Authorize a shop 

c := shopee.NewClient(shopee.Config{
    PartnerID:  10001,
    PartnerKey: "your-partner-key",
    Region:     shopee.RegionGlobal,
})
// Send the seller to c.AuthURL(redirect); Shopee redirects back with
// ?code=...&shop_id=...
tok, err := c.GetAccessToken(ctx, code, shopID)

Call a shop API 

c.SetAccessToken(tok.AccessToken)
c.SetShopID(shopID)
info, err := c.GetShopInfo(ctx)

Refresh the access token before it expires with RefreshAccessToken.

Example

Example shows the full flow: authorize a shop, exchange the code for tokens, then call a shop-scoped API. 

package main

import (
	"context"
	"fmt"
	"log"

	shopee "github.com/ultramcu/go-shopee"
)

func main() {
	c := shopee.NewClient(shopee.Config{
		PartnerID:  10001,
		PartnerKey: "your-partner-key",
		Region:     shopee.RegionGlobal,
	})

	// 1. Redirect the seller here; Shopee sends them back to your callback
	//    with ?code=...&shop_id=...
	fmt.Println(c.AuthURL("https://your.app/shopee/callback"))

	// 2. Exchange the code (read from the callback) for tokens. On success the
	//    client stores the access token + shop id.
	ctx := context.Background()
	tok, err := c.GetAccessToken(ctx, "code-from-callback", 123456)
	if err != nil {
		log.Fatal(err)
	}

	// 3. Call a shop API.
	info, err := c.GetShopInfo(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(tok.ExpireIn, info.ShopName)
}

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	// Err is the machine-readable error code, e.g. "error_auth",
	// "error_param", "error_permission".
	Err string
	// Message is the human-readable description, when provided.
	Message string
	// RequestID identifies the call on Shopee's side; quote it in support
	// tickets.
	RequestID string
}

APIError is returned when the Shopee API responds with a non-empty `error` field in its response envelope. The zero-value HTTP transport / decoding problems are returned as ordinary wrapped errors instead.

func (*APIError) Error 

func (e *APIError) Error() string

type AddItemParams added in v0.2.0 

type AddItemParams struct {
	CategoryID    int64          `json:"category_id"`
	ItemName      string         `json:"item_name"`
	Description   string         `json:"description"`
	OriginalPrice float64        `json:"original_price"`
	Weight        float64        `json:"weight"`
	Image         ItemImage      `json:"image"`
	LogisticInfo  []LogisticInfo `json:"logistic_info"`

	ItemSKU       string          `json:"item_sku,omitempty"`
	NormalStock   *int            `json:"normal_stock,omitempty"`
	AttributeList []ItemAttribute `json:"attribute_list,omitempty"`
	Brand         *ItemBrand      `json:"brand,omitempty"`
	Dimension     *Dimension      `json:"dimension,omitempty"`
	Condition     string          `json:"condition,omitempty"`
	ItemStatus    string          `json:"item_status,omitempty"`
	PreOrder      *ItemPreOrder   `json:"pre_order,omitempty"`
}

AddItemParams is the request body for AddItem (product/add_item).

It models the fields that are common to most listings; the v2 add_item endpoint accepts many more optional fields (video, wholesale, pre-order, tax, GTIN, complaint policy, size chart, etc.) that are intentionally not covered here. If you need one of those, use AddItemRaw with a map.

Required fields per the v2 docs are CategoryID, ItemName, Description, OriginalPrice, Weight, Image and LogisticInfo; the rest are optional and use omitempty so they are dropped from the JSON body when left at their zero value.

type AddressListResult added in v0.2.0 

type AddressListResult struct {
	ShowPickupAddress bool               `json:"show_pickup_address"`
	AddressList       []LogisticsAddress `json:"address_list"`
}

AddressListResult is the logistics/get_address_list response.

type Attribute added in v0.2.0 

type Attribute struct {
	AttributeID           int64            `json:"attribute_id"`
	OriginalAttributeName string           `json:"original_attribute_name"`
	DisplayAttributeName  string           `json:"display_attribute_name"`
	IsMandatory           bool             `json:"is_mandatory"`
	InputValidationType   string           `json:"input_validation_type"`
	FormatType            string           `json:"format_type"`
	DateFormatType        string           `json:"date_format_type"`
	InputType             string           `json:"input_type"`
	AttributeUnit         []string         `json:"attribute_unit"`
	AttributeValueList    []AttributeValue `json:"attribute_value_list"`
}

Attribute is one entry of product/get_attributes.

type AttributeParentBrand added in v0.2.0 

type AttributeParentBrand struct {
	ParentBrandID int64 `json:"parent_brand_id"`
}

AttributeParentBrand links an attribute value to a parent brand.

type AttributeParentValue added in v0.2.0 

type AttributeParentValue struct {
	ParentAttributeID int64 `json:"parent_attribute_id"`
	ParentValueID     int64 `json:"parent_value_id"`
}

AttributeParentValue links an attribute value to a parent attribute value (used for dependent/conditional attributes).

type AttributeValue added in v0.2.0 

type AttributeValue struct {
	ValueID             int64                  `json:"value_id"`
	OriginalValueName   string                 `json:"original_value_name"`
	DisplayValueName    string                 `json:"display_value_name"`
	ValueUnit           string                 `json:"value_unit"`
	ParentAttributeList []AttributeParentValue `json:"parent_attribute_list"`
	ParentBrandList     []AttributeParentBrand `json:"parent_brand_list"`
}

AttributeValue is one selectable value of an Attribute.

type AttributesResult added in v0.2.0 

type AttributesResult struct {
	AttributeList []Attribute `json:"attribute_list"`
}

AttributesResult is the product/get_attributes response.

type Brand added in v0.2.0 

type Brand struct {
	BrandID           int64  `json:"brand_id"`
	OriginalBrandName string `json:"original_brand_name"`
	DisplayBrandName  string `json:"display_brand_name"`
}

Brand is one entry of product/get_brand_list.

type BrandListParams added in v0.2.0 

type BrandListParams struct {
	Offset     int
	PageSize   int   // 1..100
	CategoryID int64 // category to list brands for
	// Status filters by brand status: 1 = normal, 2 = pending. Defaults to 1
	// when zero.
	Status int
}

BrandListParams are the parameters for GetBrandList.

type BrandListResult added in v0.2.0 

type BrandListResult struct {
	BrandList   []Brand `json:"brand_list"`
	HasNextPage bool    `json:"has_next_page"`
	NextOffset  int     `json:"next_offset"`
	IsMandatory bool    `json:"is_mandatory"`
	InputType   string  `json:"input_type"`
}

BrandListResult is the product/get_brand_list response. Paginate with NextOffset while HasNextPage is true.

type BuyerInvoiceInfo added in v0.2.0 

type BuyerInvoiceInfo struct {
	OrderSN       string          `json:"order_sn"`
	InvoiceType   string          `json:"invoice_type"`
	InvoiceDetail json.RawMessage `json:"invoice_detail"`
	IsRequestable bool            `json:"is_requestable"`
	Error         string          `json:"error"`
}

BuyerInvoiceInfo is one entry of order/get_buyer_invoice_info. InvoiceDetail is region-specific, so it is exposed raw.

type CancelItem added in v0.2.0 

type CancelItem struct {
	ItemID  int64 `json:"item_id"`
	ModelID int64 `json:"model_id"`
}

CancelItem identifies an order line to cancel (required by some cancel reasons, e.g. out-of-stock).

type Category added in v0.2.0 

type Category struct {
	CategoryID           int64  `json:"category_id"`
	ParentCategoryID     int64  `json:"parent_category_id"`
	OriginalCategoryName string `json:"original_category_name"`
	DisplayCategoryName  string `json:"display_category_name"`
	HasChildren          bool   `json:"has_children"`
}

Category is one entry of product/get_category.

type CategoryRecommendResult added in v0.2.0 

type CategoryRecommendResult struct {
	CategoryID []int64 `json:"category_id"`
}

CategoryRecommendResult is the product/category_recommend response, a list of recommended category ids (most relevant first) for a given item name.

type CategoryResult added in v0.2.0 

type CategoryResult struct {
	CategoryList []Category `json:"category_list"`
}

CategoryResult is the product/get_category response.

type ChannelListResult added in v0.2.0 

type ChannelListResult struct {
	LogisticsChannelList []LogisticsChannel `json:"logistics_channel_list"`
}

ChannelListResult is the logistics/get_channel_list response.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a Shopee Open Platform v2 API client. It is safe for concurrent use as long as the auth context (AccessToken / ShopID) is not mutated concurrently with in-flight requests.

func NewClient 

func NewClient(cfg Config) *Client

NewClient returns a Client configured with cfg.

func (*Client) AddItem added in v0.2.0 

func (c *Client) AddItem(ctx context.Context, p AddItemParams) (*ItemResult, error)

AddItem creates a new item (product/add_item) and returns the new item's id and status. AddItemParams models the common fields only; for advanced fields use AddItemRaw.

func (*Client) AddItemRaw added in v0.2.0 

func (c *Client) AddItemRaw(ctx context.Context, body any) (*ItemResult, error)

AddItemRaw is the escape hatch for add_item: it sends body verbatim as the JSON request, so callers can include optional fields not modelled by AddItemParams. body is typically a map[string]any or a custom struct.

func (*Client) AddModel added in v0.2.0 

func (c *Client) AddModel(ctx context.Context, itemID int64, models []ModelInit) ([]ModelInfo, error)

AddModel adds new models to an existing variation item (product/add_model) and returns the created models (with their new model ids).

func (*Client) AuthURL 

func (c *Client) AuthURL(redirectURL string) string

AuthURL returns the URL to redirect a seller to so they can authorize your app for their shop. After the seller authorizes, Shopee redirects the browser to redirectURL with `code` and `shop_id` query parameters; exchange the code for tokens with GetAccessToken.

func (*Client) CancelOrder added in v0.2.0 

func (c *Client) CancelOrder(ctx context.Context, orderSN, reason string, items []CancelItem) (int64, error)

CancelOrder cancels an order as the seller. reason is a Shopee cancel-reason enum such as "OUT_OF_STOCK" or "UNDELIVERABLE_AREA"; items is required for item-level reasons. Returns the order's update_time.

func (*Client) CategoryRecommend added in v0.2.0 

func (c *Client) CategoryRecommend(ctx context.Context, itemName string) (*CategoryRecommendResult, error)

CategoryRecommend returns category ids recommended for an item name.

func (*Client) ConfirmReturn added in v0.2.0 

func (c *Client) ConfirmReturn(ctx context.Context, returnSN string) error

ConfirmReturn accepts (confirms) a buyer's return/refund request as the seller (the returns/confirm endpoint).

func (*Client) CreateShippingDocument added in v0.2.0 

func (c *Client) CreateShippingDocument(ctx context.Context, orders []CreateShippingDocumentOrder) (*CreateShippingDocumentResult, error)

CreateShippingDocument starts an asynchronous shipping-document (air waybill) generation task for each order. Poll GetShippingDocumentResult for the task status, then fetch the file with DownloadShippingDocument once it is READY.

func (*Client) DeleteItem added in v0.2.0 

func (c *Client) DeleteItem(ctx context.Context, itemID int64) error

DeleteItem permanently deletes an item (product/delete_item).

func (*Client) DeleteModel added in v0.2.0 

func (c *Client) DeleteModel(ctx context.Context, itemID, modelID int64) error

DeleteModel deletes a single model of an item (product/delete_model).

func (*Client) DisputeReturn added in v0.2.0 

func (c *Client) DisputeReturn(ctx context.Context, p DisputeReturnParams) error

DisputeReturn raises a seller dispute against a return/refund request (the returns/dispute endpoint).

func (*Client) DownloadShippingDocument added in v0.2.0 

func (c *Client) DownloadShippingDocument(ctx context.Context, orders []ShippingDocumentOrder, shippingDocumentType string) ([]byte, error)

DownloadShippingDocument fetches the generated shipping document (air waybill) as a single binary stream — for one or more orders — concatenated into one file. The endpoint returns the document bytes directly (typically a PDF), not a JSON envelope, so this reads the raw response body. shippingDocumentType is optional; pass "" to use the default. Each order's document task must already be READY (see CreateShippingDocument / GetShippingDocumentResult).

func (*Client) GetAccessToken 

func (c *Client) GetAccessToken(ctx context.Context, code string, shopID int64) (*TokenResponse, error)

GetAccessToken exchanges the authorization code (from the AuthURL redirect) for an access/refresh token pair for shopID. On success the new tokens and shopID are also stored on the client, so subsequent shop-scoped calls work without further setup.

func (*Client) GetAddressList added in v0.2.0 

func (c *Client) GetAddressList(ctx context.Context) (*AddressListResult, error)

GetAddressList returns the shop's configured pickup/return/seller addresses. For integrated channels, use it to find the pickup address for pickup-mode orders.

func (*Client) GetAttributes added in v0.2.0 

func (c *Client) GetAttributes(ctx context.Context, categoryID int64, language string) (*AttributesResult, error)

GetAttributes returns the attributes of a category. language is an optional display language code; pass "" to use the shop default.

Some Shopee API versions expose this as product/get_attribute_tree; v2 currently uses product/get_attributes (confirmed against passwind's reference). TODO: verify against sandbox.

func (*Client) GetBrandList added in v0.2.0 

func (c *Client) GetBrandList(ctx context.Context, p BrandListParams) (*BrandListResult, error)

GetBrandList lists the brands available for a category.

func (*Client) GetBuyerInvoiceInfo added in v0.2.0 

func (c *Client) GetBuyerInvoiceInfo(ctx context.Context, orderSNList []string) ([]BuyerInvoiceInfo, error)

GetBuyerInvoiceInfo returns the buyer-supplied invoice info for the given orders (the order/get_buyer_invoice_info endpoint).

func (*Client) GetCategory added in v0.2.0 

func (c *Client) GetCategory(ctx context.Context, language string) (*CategoryResult, error)

GetCategory returns the shop's category tree. language is an optional display language code (e.g. "en", "zh-Hans"); pass "" to use the shop default.

func (*Client) GetChannelList added in v0.2.0 

func (c *Client) GetChannelList(ctx context.Context) (*ChannelListResult, error)

GetChannelList returns all logistics channels supported for the shop, with each channel's fee type, weight/size limits and whether it is enabled.

func (*Client) GetEscrowDetail added in v0.2.0 

func (c *Client) GetEscrowDetail(ctx context.Context, orderSN string) (*EscrowDetail, error)

GetEscrowDetail fetches the accounting (escrow) detail for an order — the income breakdown Shopee uses to compute the seller's payout.

func (*Client) GetEscrowList added in v0.2.0 

func (c *Client) GetEscrowList(ctx context.Context, p EscrowListParams) (*EscrowListResult, error)

GetEscrowList lists settled escrow records whose release time falls in the given window.

func (*Client) GetItemBaseInfo 

func (c *Client) GetItemBaseInfo(ctx context.Context, itemIDs []int64) (*ItemBaseInfoResult, error)

GetItemBaseInfo fetches base info for up to 50 item ids.

func (*Client) GetItemExtraInfo added in v0.2.0 

func (c *Client) GetItemExtraInfo(ctx context.Context, itemIDs []int64) (*ItemExtraInfoResult, error)

GetItemExtraInfo fetches extra engagement info (sales, views, likes, rating, comment counts) for up to 50 item ids (product/get_item_extra_info).

func (*Client) GetItemLimit added in v0.2.0 

func (c *Client) GetItemLimit(ctx context.Context, categoryID int64) (*ItemLimit, error)

GetItemLimit returns the per-category item creation limits (price range, stock, name length, image count) for the given category.

func (*Client) GetItemList 

func (c *Client) GetItemList(ctx context.Context, p ItemListParams) (*ItemListResult, error)

GetItemList lists the shop's item ids and statuses.

func (*Client) GetMassShippingParameter added in v0.2.0 

func (c *Client) GetMassShippingParameter(ctx context.Context, orderSNList []string) (*MassShippingParameter, error)

GetMassShippingParameter returns the shipping options and required parameters shared across a batch of orders that ship via the same channel — the mass counterpart of GetShippingParameter.

TODO: verify against sandbox — the get_mass_shipping_parameter request/ response shape (notably whether the orders go in order_list and the exact response field names) is not confirmed against a live response.

func (*Client) GetModelList added in v0.2.0 

func (c *Client) GetModelList(ctx context.Context, itemID int64) (*ModelListResult, error)

GetModelList returns an item's tier variations and models (product/get_model_list).

func (*Client) GetOrderDetail 

func (c *Client) GetOrderDetail(
	ctx context.Context,
	orderSNList []string,
	optionalFields ...string,
) (*OrderDetailResult, error)

GetOrderDetail fetches full details for up to 50 order serial numbers. optionalFields are sent as response_optional_fields, e.g. "item_list", "buyer_username", "recipient_address" — Shopee omits some fields unless requested.

func (*Client) GetOrderList 

func (c *Client) GetOrderList(ctx context.Context, p OrderListParams) (*OrderListResult, error)

GetOrderList lists order serial numbers within a time window.

Example

ExampleClient_GetOrderList lists orders in a time window for an already-authorized shop. 

package main

import (
	"context"
	"fmt"
	"log"

	shopee "github.com/ultramcu/go-shopee"
)

func main() {
	c := shopee.NewClient(shopee.Config{
		PartnerID:   10001,
		PartnerKey:  "your-partner-key",
		Region:      shopee.RegionGlobal,
		ShopID:      123456,
		AccessToken: "access-token",
	})
	res, err := c.GetOrderList(context.Background(), shopee.OrderListParams{
		TimeRangeField: "create_time",
		TimeFrom:       1609459200,
		TimeTo:         1609545600,
		PageSize:       50,
		OrderStatus:    "READY_TO_SHIP",
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, o := range res.OrderList {
		fmt.Println(o.OrderSN)
	}
}

func (*Client) GetPaymentMethodList added in v0.2.0 

func (c *Client) GetPaymentMethodList(ctx context.Context) (*PaymentMethodListResult, error)

GetPaymentMethodList returns the payment methods available to the shop.

func (*Client) GetPayoutDetail added in v0.2.0 

func (c *Client) GetPayoutDetail(ctx context.Context, p PayoutDetailParams) (*PayoutDetailResult, error)

GetPayoutDetail returns settlement (payout) records in the given time window. Mainly relevant to cross-border shops.

func (*Client) GetReturnDetail added in v0.2.0 

func (c *Client) GetReturnDetail(ctx context.Context, returnSN string) (*ReturnInfo, error)

GetReturnDetail fetches the full detail of a single return/refund request.

func (*Client) GetReturnList added in v0.2.0 

func (c *Client) GetReturnList(ctx context.Context, p ReturnListParams) (*ReturnListResult, error)

GetReturnList lists the shop's return/refund requests.

func (*Client) GetShipmentList added in v0.2.0 

func (c *Client) GetShipmentList(ctx context.Context, cursor string, pageSize int) (*ShipmentListResult, error)

GetShipmentList lists orders that are ready to ship / pending shipment.

func (*Client) GetShippingDocumentParameter added in v0.2.0 

func (c *Client) GetShippingDocumentParameter(ctx context.Context, orders []ShippingDocumentOrder) (*ShippingDocumentParameterResult, error)

GetShippingDocumentParameter returns the selectable and suggested shipping-document types for each requested order — call it before CreateShippingDocument to pick a valid shipping_document_type.

func (*Client) GetShippingDocumentResult added in v0.2.0 

func (c *Client) GetShippingDocumentResult(ctx context.Context, orders []GetShippingDocumentResultOrder) (*ShippingDocumentResult, error)

GetShippingDocumentResult reports the status of the shipping-document tasks created by CreateShippingDocument. A document can be downloaded once its Status is "READY".

func (*Client) GetShippingParameter added in v0.2.0 

func (c *Client) GetShippingParameter(ctx context.Context, orderSN string) (*ShippingParameter, error)

GetShippingParameter returns the shipping options and required parameters for an order — call it before ShipOrder to learn whether the order ships by pickup or dropoff and which fields are needed.

func (*Client) GetShopInfo 

func (c *Client) GetShopInfo(ctx context.Context) (*ShopInfo, error)

GetShopInfo returns information about the authorized shop. Requires a valid access token and shop id (set via OAuth or SetAccessToken / SetShopID).

func (*Client) GetTrackingInfo added in v0.2.0 

func (c *Client) GetTrackingInfo(ctx context.Context, orderSN string) (*TrackingInfo, error)

GetTrackingInfo returns the full tracking history for an order.

func (*Client) GetTrackingNumber added in v0.2.0 

func (c *Client) GetTrackingNumber(ctx context.Context, orderSN string) (string, error)

GetTrackingNumber returns the carrier tracking number assigned to an order.

func (*Client) GetWalletTransactionList added in v0.2.0 

func (c *Client) GetWalletTransactionList(ctx context.Context, p WalletTransactionParams) (*WalletTransactionResult, error)

GetWalletTransactionList returns the shop wallet's transaction records, optionally filtered by time window, wallet type and transaction type.

func (*Client) HandleBuyerCancellation added in v0.2.0 

func (c *Client) HandleBuyerCancellation(ctx context.Context, orderSN, operation string) (int64, error)

HandleBuyerCancellation accepts or rejects a buyer's cancellation request. operation is "ACCEPT" or "REJECT". Returns the order's update_time.

func (*Client) InitTierVariation added in v0.2.0 

func (c *Client) InitTierVariation(ctx context.Context, itemID int64, tiers []TierVariation, models []ModelInit) (*ModelListResult, error)

InitTierVariation turns a no-variation item into a variation item by defining its tier variations and the initial set of models (product/init_tier_variation). It returns the created tier variations and models (with their new model ids).

func (*Client) QueryReturnProof added in v0.2.0 

func (c *Client) QueryReturnProof(ctx context.Context, returnSN string) (*ReturnProof, error)

QueryReturnProof returns the proof/evidence attached to a return request (the returns/query_proof endpoint).

func (*Client) RefreshAccessToken 

func (c *Client) RefreshAccessToken(ctx context.Context, refreshToken string, shopID int64) (*TokenResponse, error)

RefreshAccessToken obtains a fresh access/refresh token pair using a refresh token for shopID. On success the new tokens are stored on the client. Refresh tokens are single-use: keep the returned RefreshToken for the next refresh.

func (*Client) SetAccessToken 

func (c *Client) SetAccessToken(token string)

SetAccessToken updates the access token used for shop-scoped requests.

func (*Client) SetNote added in v0.2.0 

func (c *Client) SetNote(ctx context.Context, orderSN, note string) error

SetNote sets (or replaces) the seller's note on an order.

func (*Client) SetShopID 

func (c *Client) SetShopID(shopID int64)

SetShopID updates the shop id used for shop-scoped requests.

func (*Client) ShipOrder added in v0.2.0 

func (c *Client) ShipOrder(ctx context.Context, p ShipOrderParams) error

ShipOrder arranges shipment for an order (the order/ship_order endpoint).

func (*Client) ShopID 

func (c *Client) ShopID() int64

ShopID reports the configured shop id.

func (*Client) UnlistItem added in v0.2.0 

func (c *Client) UnlistItem(ctx context.Context, items []UnlistEntry) (*UnlistItemResult, error)

UnlistItem hides (unlist=true) or re-lists (unlist=false) items (product/unlist_item). It returns the per-item success and failure lists from the response.

func (*Client) UpdateItem added in v0.2.0 

func (c *Client) UpdateItem(ctx context.Context, p UpdateItemParams) (*ItemResult, error)

UpdateItem edits an existing item (product/update_item).

func (*Client) UpdateItemRaw added in v0.2.0 

func (c *Client) UpdateItemRaw(ctx context.Context, body any) (*ItemResult, error)

UpdateItemRaw is the escape hatch for update_item; see AddItemRaw. body must include "item_id".

func (*Client) UpdateModel added in v0.2.0 

func (c *Client) UpdateModel(ctx context.Context, itemID int64, models []ModelUpdate) error

UpdateModel edits existing models of an item (product/update_model). The response carries only the base envelope, so this returns an error only.

func (*Client) UpdatePrice added in v0.2.0 

func (c *Client) UpdatePrice(ctx context.Context, itemID int64, prices []PriceUpdate) (*UpdatePriceResult, error)

UpdatePrice sets the original price for one or more models of an item (product/update_price).

func (*Client) UpdateStock added in v0.2.0 

func (c *Client) UpdateStock(ctx context.Context, itemID int64, stock []StockUpdate) (*UpdateStockResult, error)

UpdateStock sets the seller stock for one or more models of an item (product/update_stock).

This uses the classic per-model normal_stock form. Some regions/versions expect a richer stock_list entry (e.g. a per-location seller_stock array); callers in those regions should adapt the StockUpdate shape accordingly. TODO: verify against sandbox for your region.

func (*Client) UpdateTierVariation added in v0.2.0 

func (c *Client) UpdateTierVariation(ctx context.Context, itemID int64, tiers []TierVariation) error

UpdateTierVariation replaces an item's tier-variation definitions (product/update_tier_variation). The response carries only the base envelope, so this returns an error only.

type Config 

type Config struct {
	PartnerID   int64
	PartnerKey  string
	Region      Region
	ShopID      int64
	AccessToken string

	// HTTPClient is used for all requests; defaults to a client with a 30s
	// timeout.
	HTTPClient *http.Client
	// BaseURL overrides the host derived from Region. Useful for a region
	// without a dedicated constant, or for pointing tests at a local server.
	BaseURL string
	// contains filtered or unexported fields
}

Config configures a Client. PartnerID and PartnerKey come from the Shopee Open Platform console and are always required. ShopID and AccessToken are obtained from the OAuth flow (see AuthURL / GetAccessToken) and are required for shop-scoped APIs; they can also be set later with SetShopID / SetAccessToken.

type CreateShippingDocumentEntry added in v0.2.0 

type CreateShippingDocumentEntry struct {
	OrderSN       string `json:"order_sn"`
	PackageNumber string `json:"package_number"`
	FailError     string `json:"fail_error"`
	FailMessage   string `json:"fail_message"`
}

CreateShippingDocumentEntry is one entry of the logistics/create_shipping_document response. A non-empty FailError indicates the document task could not be created for that order.

type CreateShippingDocumentOrder added in v0.2.0 

type CreateShippingDocumentOrder struct {
	OrderSN              string `json:"order_sn"`
	PackageNumber        string `json:"package_number,omitempty"`
	TrackingNumber       string `json:"tracking_number,omitempty"`
	ShippingDocumentType string `json:"shipping_document_type,omitempty"`
}

CreateShippingDocumentOrder is one order in a CreateShippingDocument request. ShippingDocumentType is a value from GetShippingDocumentParameter (e.g. "NORMAL_AIR_WAYBILL", "THERMAL_AIR_WAYBILL"); TrackingNumber is required for some non-integrated channels.

type CreateShippingDocumentResult added in v0.2.0 

type CreateShippingDocumentResult struct {
	ResultList []CreateShippingDocumentEntry `json:"result_list"`
}

CreateShippingDocumentResult is the logistics/create_shipping_document response.

type Dimension added in v0.2.0 

type Dimension struct {
	PackageLength int `json:"package_length"`
	PackageWidth  int `json:"package_width"`
	PackageHeight int `json:"package_height"`
}

Dimension is the parcel dimension block (centimetres).

type DisputeReturnParams added in v0.2.0 

type DisputeReturnParams struct {
	ReturnSN          string
	Email             string
	DisputeReason     string
	DisputeTextReason string
	Images            []string
}

DisputeReturnParams are the parameters for DisputeReturn.

Email is the seller contact email. DisputeReason is a Shopee dispute-reason enum; DisputeTextReason is free text supporting the dispute. Images is an optional list of image identifiers (image ids/urls) attached as evidence — upload them first with UploadReturnProof.

type EscrowDetail added in v0.2.0 

type EscrowDetail struct {
	OrderSN           string      `json:"order_sn"`
	BuyerUserName     string      `json:"buyer_user_name"`
	ReturnOrderSNList []string    `json:"return_order_sn_list"`
	OrderIncome       OrderIncome `json:"order_income"`
}

EscrowDetail is the payment/get_escrow_detail response: the accounting detail of a single order.

type EscrowListItem added in v0.2.0 

type EscrowListItem struct {
	OrderSN           string  `json:"order_sn"`
	PayoutAmount      float64 `json:"payout_amount"`
	EscrowReleaseTime int64   `json:"escrow_release_time"`
}

EscrowListItem is one entry of payment/get_escrow_list.

type EscrowListParams added in v0.2.0 

type EscrowListParams struct {
	ReleaseTimeFrom int64 // unix seconds, inclusive; required
	ReleaseTimeTo   int64 // unix seconds; required
	PageSize        int   // 1..100; optional, Shopee defaults apply when 0
	PageNo          int   // 1-based; optional
}

EscrowListParams are the parameters for GetEscrowList. ReleaseTimeFrom and ReleaseTimeTo are required unix-second bounds on the escrow release time; the window may span at most 15 days.

type EscrowListResult added in v0.2.0 

type EscrowListResult struct {
	EscrowList []EscrowListItem `json:"escrow_list"`
	More       bool             `json:"more"`
}

EscrowListResult is the payment/get_escrow_list response. Paginate with PageNo while More is true.

type GetShippingDocumentResultOrder added in v0.2.0 

type GetShippingDocumentResultOrder struct {
	OrderSN              string `json:"order_sn"`
	PackageNumber        string `json:"package_number,omitempty"`
	ShippingDocumentType string `json:"shipping_document_type,omitempty"`
}

GetShippingDocumentResultOrder is one order in a GetShippingDocumentResult request. ShippingDocumentType should match the value used when the task was created.

type ItemAttribute added in v0.2.0 

type ItemAttribute struct {
	AttributeID        int64                `json:"attribute_id"`
	AttributeValueList []ItemAttributeValue `json:"attribute_value_list"`
}

ItemAttribute is one attribute/value pair for an item, as required by the item's category (see product/get_attributes for the allowed ids/values).

type ItemAttributeValue added in v0.2.0 

type ItemAttributeValue struct {
	ValueID           int64  `json:"value_id,omitempty"`
	OriginalValueName string `json:"original_value_name,omitempty"`
	ValueUnit         string `json:"value_unit,omitempty"`
}

ItemAttributeValue is a single value for an ItemAttribute.

type ItemBaseInfo 

type ItemBaseInfo struct {
	ItemID      int64           `json:"item_id"`
	CategoryID  int64           `json:"category_id"`
	ItemName    string          `json:"item_name"`
	Description string          `json:"description"`
	ItemSKU     string          `json:"item_sku"`
	ItemStatus  string          `json:"item_status"`
	CreateTime  int64           `json:"create_time"`
	UpdateTime  int64           `json:"update_time"`
	Weight      string          `json:"weight"`
	PriceInfo   []PriceInfo     `json:"price_info"`
	StockInfoV2 json.RawMessage `json:"stock_info_v2"`
}

ItemBaseInfo is a subset of an item from product/get_item_base_info. StockInfoV2 is kept raw because its shape varies by region/version.

type ItemBaseInfoResult 

type ItemBaseInfoResult struct {
	ItemList []ItemBaseInfo `json:"item_list"`
}

ItemBaseInfoResult is the product/get_item_base_info response.

type ItemBrand added in v0.2.0 

type ItemBrand struct {
	BrandID           int64  `json:"brand_id"`
	OriginalBrandName string `json:"original_brand_name"`
}

ItemBrand identifies an item's brand. Use BrandID 0 with the special "NoBrand" name when a category requires a brand but the item has none.

type ItemExtraInfo added in v0.2.0 

type ItemExtraInfo struct {
	ItemID     int64 `json:"item_id"`
	Sale       int   `json:"sale"`
	Views      int   `json:"views"`
	Likes      int   `json:"likes"`
	RatingStar struct {
		RatingStar  float64 `json:"rating_star"`
		RatingCount []int   `json:"rating_count"`
	} `json:"rating_star"`
	CommentCount int `json:"comment_count"`
}

ItemExtraInfo is one entry of product/get_item_extra_info. The endpoint returns engagement/sales counters that are not part of the base info.

TODO: verify against sandbox. Field names follow the v2 docs but the exact set varies by region/version; fields not modelled here are simply ignored.

type ItemExtraInfoResult added in v0.2.0 

type ItemExtraInfoResult struct {
	ItemList []ItemExtraInfo `json:"item_list"`
}

ItemExtraInfoResult is the product/get_item_extra_info response.

type ItemImage added in v0.2.0 

type ItemImage struct {
	ImageIDList  []string `json:"image_id_list,omitempty"`
	ImageURLList []string `json:"image_url_list,omitempty"`
}

ItemImage is the image block of an item. ImageIDList holds image ids returned by the media-space upload API, ordered as they should appear.

type ItemLimit added in v0.2.0 

type ItemLimit struct {
	PriceLimit   PriceLimit `json:"price_limit"`
	StockLimit   int        `json:"stock_limit"`
	ItemNameMin  int        `json:"item_name_length_min"`
	ItemNameMax  int        `json:"item_name_length_max"`
	ItemImageMin int        `json:"item_image_count_min"`
	ItemImageMax int        `json:"item_image_count_max"`
}

ItemLimit is the product/get_item_limit response: the per-category limits that apply when creating or updating an item.

TODO: verify against sandbox — not present in passwind's reference; field set is based on the Shopee Open Platform v2 docs.

type ItemListEntry 

type ItemListEntry struct {
	ItemID     int64  `json:"item_id"`
	ItemStatus string `json:"item_status"`
	UpdateTime int64  `json:"update_time"`
}

ItemListEntry is one entry of product/get_item_list.

type ItemListParams 

type ItemListParams struct {
	Offset   int
	PageSize int // 1..100
	// ItemStatus filters by status, e.g. "NORMAL", "BANNED", "UNLIST",
	// "REVIEWING". Empty defaults to "NORMAL".
	ItemStatus string
}

ItemListParams are the parameters for GetItemList.

type ItemListResult 

type ItemListResult struct {
	Item        []ItemListEntry `json:"item"`
	TotalCount  int             `json:"total_count"`
	HasNextPage bool            `json:"has_next_page"`
	NextOffset  int             `json:"next_offset"`
}

ItemListResult is the product/get_item_list response. Paginate with NextOffset while HasNextPage is true.

type ItemPreOrder added in v0.2.0 

type ItemPreOrder struct {
	IsPreOrder bool `json:"is_pre_order"`
	DaysToShip *int `json:"days_to_ship,omitempty"`
}

ItemPreOrder describes pre-order shipping. When IsPreOrder is true, DaysToShip must be set within the category's allowed range; otherwise it is ignored.

type ItemResult added in v0.2.0 

type ItemResult struct {
	ItemID     int64  `json:"item_id"`
	ItemStatus string `json:"item_status"`
	CreateTime int64  `json:"create_time"`
	UpdateTime int64  `json:"update_time"`
}

ItemResult is the trimmed response of add_item / update_item. The full response echoes the whole item; only the ids and status most callers need after a write are surfaced here. To read back the full item, follow up with GetItemBaseInfo.

type LogisticInfo added in v0.2.0 

type LogisticInfo struct {
	LogisticID  int64   `json:"logistic_id"`
	Enabled     bool    `json:"enabled"`
	ShippingFee float64 `json:"shipping_fee,omitempty"`
	SizeID      int64   `json:"size_id,omitempty"`
	IsFree      bool    `json:"is_free,omitempty"`
}

LogisticInfo enables (or disables) a logistics channel for an item. Enabled is required; ShippingFee/SizeID/IsFree apply to channels that need them.

type LogisticsAddress added in v0.2.0 

type LogisticsAddress struct {
	AddressID   int64    `json:"address_id"`
	Region      string   `json:"region"`
	State       string   `json:"state"`
	City        string   `json:"city"`
	Address     string   `json:"address"`
	Zipcode     string   `json:"zipcode"`
	District    string   `json:"district"`
	Town        string   `json:"town"`
	AddressFlag []string `json:"address_flag"`
	AddressType []string `json:"address_type"`
}

LogisticsAddress is one entry of logistics/get_address_list.

type LogisticsChannel added in v0.2.0 

type LogisticsChannel struct {
	LogisticsChannelID   int64                `json:"logistics_channel_id"`
	LogisticsChannelName string               `json:"logistics_channel_name"`
	CODEnabled           bool                 `json:"cod_enabled"`
	Enabled              bool                 `json:"enabled"`
	FeeType              string               `json:"fee_type"`
	Preferred            bool                 `json:"preferred"`
	SizeList             []LogisticsSize      `json:"size_list"`
	WeightLimit          LogisticsWeightLimit `json:"weight_limit"`
	ItemMaxDimension     LogisticsDimension   `json:"item_max_dimension"`
	VolumeLimit          LogisticsVolumeLimit `json:"volume_limit"`
}

LogisticsChannel is one entry of logistics/get_channel_list.

type LogisticsDimension added in v0.2.0 

type LogisticsDimension struct {
	Height float64 `json:"height"`
	Width  float64 `json:"width"`
	Length float64 `json:"length"`
	Unit   string  `json:"unit"`
}

LogisticsDimension is a channel's accepted per-item dimension limit.

type LogisticsSize added in v0.2.0 

type LogisticsSize struct {
	SizeID       string  `json:"size_id"`
	Name         string  `json:"name"`
	DefaultPrice float64 `json:"default_price"`
}

LogisticsSize is one size tier offered by a logistics channel (size-based fee channels only).

type LogisticsVolumeLimit added in v0.2.0 

type LogisticsVolumeLimit struct {
	ItemMaxVolume float64 `json:"item_max_volume"`
	ItemMinVolume float64 `json:"item_min_volume"`
}

LogisticsVolumeLimit is a channel's accepted per-item volume range.

type LogisticsWeightLimit added in v0.2.0 

type LogisticsWeightLimit struct {
	ItemMaxWeight float64 `json:"item_max_weight"`
	ItemMinWeight float64 `json:"item_min_weight"`
}

LogisticsWeightLimit is a channel's accepted per-item weight range, in kg.

type MassShippingParameter added in v0.2.0 

type MassShippingParameter struct {
	InfoNeeded ShippingInfoNeeded `json:"info_needed"`
}

MassShippingParameter is the per-channel parameter block returned by logistics/get_mass_shipping_parameter. InfoNeeded lists the fields each shipping method requires; the Dropoff and Pickup option lists vary by channel and are exposed raw.

type ModelInfo added in v0.2.0 

type ModelInfo struct {
	ModelID     int64            `json:"model_id"`
	TierIndex   []int            `json:"tier_index"`
	ModelSKU    string           `json:"model_sku"`
	PriceInfo   []PriceInfo      `json:"price_info"`
	StockInfo   []ModelStockInfo `json:"stock_info"`
	PromotionID int64            `json:"promotion_id"`
}

ModelInfo is one variation model of an item as returned by get_model_list, init_tier_variation and add_model. TierIndex maps the model to a combination of TierVariation options (one index per tier, in tier order). PriceInfo reuses the package's PriceInfo type.

type ModelInit added in v0.2.0 

type ModelInit struct {
	TierIndex     []int   `json:"tier_index"`
	ModelSKU      string  `json:"model_sku,omitempty"`
	OriginalPrice float64 `json:"original_price"`
	NormalStock   int     `json:"normal_stock"`
}

ModelInit is one model to create when initialising tier variations. TierIndex must have one entry per tier (in tier order); ModelSKU/OriginalPrice/ NormalStock seed the model.

type ModelListResult added in v0.2.0 

type ModelListResult struct {
	TierVariation []TierVariation `json:"tier_variation"`
	Model         []ModelInfo     `json:"model"`
}

ModelListResult is the product/get_model_list response.

type ModelStockInfo added in v0.2.0 

type ModelStockInfo struct {
	StockType       int    `json:"stock_type"`
	StockLocationID string `json:"stock_location_id"`
	NormalStock     int    `json:"normal_stock"`
	CurrentStock    int    `json:"current_stock"`
	ReservedStock   int    `json:"reserved_stock"`
}

ModelStockInfo is one stock entry of a model. Its shape varies by region / version (single-warehouse vs. multi-location), so the common fields are modelled and the rest can be ignored.

type ModelUpdate added in v0.2.0 

type ModelUpdate struct {
	ModelID  int64  `json:"model_id"`
	ModelSKU string `json:"model_sku"`
}

ModelUpdate edits an existing model. ModelID is required; only ModelSKU is editable through this endpoint (use UpdatePrice / UpdateStock to change a model's price or stock).

type OrderDetail 

type OrderDetail struct {
	OrderSN         string      `json:"order_sn"`
	Region          string      `json:"region"`
	Currency        string      `json:"currency"`
	TotalAmount     float64     `json:"total_amount"`
	OrderStatus     string      `json:"order_status"`
	BuyerUserID     int64       `json:"buyer_user_id"`
	BuyerUsername   string      `json:"buyer_username"`
	PaymentMethod   string      `json:"payment_method"`
	ShippingCarrier string      `json:"shipping_carrier"`
	CreateTime      int64       `json:"create_time"`
	UpdateTime      int64       `json:"update_time"`
	ItemList        []OrderItem `json:"item_list"`
}

OrderDetail is a subset of an order from order/get_order_detail.

type OrderDetailResult 

type OrderDetailResult struct {
	OrderList []OrderDetail `json:"order_list"`
}

OrderDetailResult is the order/get_order_detail response.

type OrderIncome added in v0.2.0 

type OrderIncome struct {
	// EscrowAmount is the net amount the seller is expected to receive for the
	// order. It can change until the order is completed.
	EscrowAmount float64 `json:"escrow_amount"`
	// BuyerTotalAmount is the total amount paid by the buyer (item price +
	// shipping borne by buyer, offset by Shopee promotions).
	BuyerTotalAmount float64 `json:"buyer_total_amount"`
	// OriginalPrice is the listed price of the items before discounts.
	OriginalPrice float64 `json:"original_price"`
	// SellerDiscount and ShopeeDiscount are the discount amounts borne by the
	// seller and by Shopee respectively.
	SellerDiscount float64 `json:"seller_discount"`
	ShopeeDiscount float64 `json:"shopee_discount"`
	// VoucherFromSeller and VoucherFromShopee are voucher amounts borne by the
	// seller and by Shopee respectively.
	VoucherFromSeller float64 `json:"voucher_from_seller"`
	VoucherFromShopee float64 `json:"voucher_from_shopee"`
	// Coins is the amount paid by the buyer with Shopee coins.
	Coins float64 `json:"coins"`
	// CommissionFee is the platform commission charged by Shopee.
	CommissionFee float64 `json:"commission_fee"`
	// ServiceFee is the service fee charged by Shopee.
	ServiceFee float64 `json:"service_fee"`
	// SellerTransactionFee is the transaction (e.g. credit-card) fee borne by
	// the seller.
	SellerTransactionFee float64 `json:"seller_transaction_fee"`
	// ActualShippingFee is the actual shipping fee for the order.
	ActualShippingFee float64 `json:"actual_shipping_fee"`
	// BuyerPaidShippingFee is the shipping fee paid by the buyer.
	BuyerPaidShippingFee float64 `json:"buyer_paid_shipping_fee"`
	// ShopeeShippingRebate is the shipping rebate provided by Shopee.
	ShopeeShippingRebate float64 `json:"shopee_shipping_rebate"`
	// SellerReturnRefund is the amount refunded to the buyer for returns,
	// borne by the seller.
	SellerReturnRefund float64 `json:"seller_return_refund"`
}

OrderIncome is the accounting breakdown for an order, returned inside an escrow (payment) detail. Shopee's income model is large and varies by region and order type; the fields below are the commonly-present ones. Amounts are in the shop's currency. Fields not modelled here can still be read via the raw response if needed.

TODO: verify the full field set and exact json tags against the sandbox — the payment API exposes many region-specific fields (taxes, instalment, credit- card promotions) that are intentionally left out to avoid inventing names.

type OrderItem 

type OrderItem struct {
	ItemID                 int64   `json:"item_id"`
	ItemName               string  `json:"item_name"`
	ItemSKU                string  `json:"item_sku"`
	ModelID                int64   `json:"model_id"`
	ModelName              string  `json:"model_name"`
	ModelQuantityPurchased int     `json:"model_quantity_purchased"`
	ModelOriginalPrice     float64 `json:"model_original_price"`
	ModelDiscountedPrice   float64 `json:"model_discounted_price"`
}

OrderItem is one line item within an order.

type OrderListItem 

type OrderListItem struct {
	OrderSN string `json:"order_sn"`
}

OrderListItem is one entry of order/get_order_list.

type OrderListParams 

type OrderListParams struct {
	// TimeRangeField is "create_time" or "update_time".
	TimeRangeField string
	TimeFrom       int64 // unix seconds, inclusive
	TimeTo         int64 // unix seconds; the window may span at most 15 days
	PageSize       int   // 1..100
	Cursor         string
	// OrderStatus optionally filters by status, e.g. "UNPAID",
	// "READY_TO_SHIP", "SHIPPED", "COMPLETED", "CANCELLED". Empty = all.
	OrderStatus string
}

OrderListParams are the parameters for GetOrderList.

type OrderListResult 

type OrderListResult struct {
	OrderList  []OrderListItem `json:"order_list"`
	More       bool            `json:"more"`
	NextCursor string          `json:"next_cursor"`
}

OrderListResult is the order/get_order_list response. Paginate with NextCursor while More is true.

type PaymentMethod added in v0.2.0 

type PaymentMethod struct {
	PaymentMethodName string `json:"payment_method_name"`
}

PaymentMethod is one entry of payment/get_payment_method_list.

TODO: verify field names against the sandbox — the response shape for the payment-method list is not well documented publicly.

type PaymentMethodListResult added in v0.2.0 

type PaymentMethodListResult struct {
	PaymentMethodList []PaymentMethod `json:"payment_method_list"`
}

PaymentMethodListResult is the payment/get_payment_method_list response.

type PayoutDetailItem added in v0.2.0 

type PayoutDetailItem struct {
	PayoutAmount float64 `json:"payout_amount"`
	PayoutTime   int64   `json:"payout_time"`
	Currency     string  `json:"currency"`
}

PayoutDetailItem is one entry of payment/get_payout_detail. The payout (settlement) endpoint is primarily used by cross-border (CB) shops; the modelled fields are the common settlement amounts.

TODO: verify field names against the sandbox — the payout schema is sparsely documented publicly, so this struct is intentionally conservative.

type PayoutDetailParams added in v0.2.0 

type PayoutDetailParams struct {
	PageSize       int   // required
	PageNo         int   // 1-based; required
	PayoutTimeFrom int64 // unix seconds, inclusive; required
	PayoutTimeTo   int64 // unix seconds; required
}

PayoutDetailParams are the parameters for GetPayoutDetail. All four are required by the API; PayoutTimeFrom and PayoutTimeTo are unix-second bounds on the payout time.

type PayoutDetailResult added in v0.2.0 

type PayoutDetailResult struct {
	PayoutList []PayoutDetailItem `json:"payout_list"`
	More       bool               `json:"more"`
}

PayoutDetailResult is the payment/get_payout_detail response. Paginate with PageNo while More is true.

type PriceFailure added in v0.2.0 

type PriceFailure struct {
	ModelID      int64  `json:"model_id"`
	FailedReason string `json:"failed_reason"`
}

PriceFailure is one failed entry of update_price.

type PriceInfo 

type PriceInfo struct {
	Currency      string  `json:"currency"`
	OriginalPrice float64 `json:"original_price"`
	CurrentPrice  float64 `json:"current_price"`
}

PriceInfo is the pricing block of an item.

type PriceLimit added in v0.2.0 

type PriceLimit struct {
	MinLimit float64 `json:"min_limit"`
	MaxLimit float64 `json:"max_limit"`
}

PriceLimit is the allowed price range for items in a category.

type PriceSuccess added in v0.2.0 

type PriceSuccess struct {
	ModelID       int64   `json:"model_id"`
	OriginalPrice float64 `json:"original_price"`
}

PriceSuccess is one successful entry of update_price.

type PriceUpdate added in v0.2.0 

type PriceUpdate struct {
	ModelID       int64   `json:"model_id"`
	OriginalPrice float64 `json:"original_price"`
}

PriceUpdate sets the original price for a model (use ModelID 0 for an item without variations).

type Region 

type Region int

Region selects which Shopee Open Platform host the client talks to. 

const (
	// RegionGlobal is the live host for all non-China regions
	// (partner.shopeemobile.com).
	RegionGlobal Region = iota
	// RegionSandbox is the global test host (partner.test-stable.shopeemobile.com).
	RegionSandbox
	// RegionChina is the live China host (openplatform.shopee.cn).
	RegionChina
	// RegionChinaSandbox is the China test host
	// (openplatform.test-stable.shopee.cn).
	RegionChinaSandbox
)

type ReturnInfo added in v0.2.0 

type ReturnInfo struct {
	ReturnSN       string       `json:"return_sn"`
	OrderSN        string       `json:"order_sn"`
	ReturnStatus   string       `json:"return_status"`
	Reason         string       `json:"reason"`
	TextReason     string       `json:"text_reason"`
	RefundAmount   float64      `json:"refund_amount"`
	Currency       string       `json:"currency"`
	CreateTime     int64        `json:"create_time"`
	UpdateTime     int64        `json:"update_time"`
	DueDate        int64        `json:"due_date"`
	TrackingNumber string       `json:"tracking_number"`
	User           *ReturnUser  `json:"user"`
	Item           []ReturnItem `json:"item"`
}

ReturnInfo is a single return/refund request as returned by the returns endpoints. The list endpoint returns a lighter subset; the detail endpoint fills in user/item and the proof/negotiation blocks.

TODO: verify against sandbox — the exact field set and amount types (float vs string) differ slightly by region/version; fields here are the commonly documented ones and kept conservative.

type ReturnItem added in v0.2.0 

type ReturnItem struct {
	ItemID            int64   `json:"item_id"`
	ModelID           int64   `json:"model_id"`
	ItemName          string  `json:"name"`
	ItemSKU           string  `json:"item_sku"`
	ModelSKU          string  `json:"variation_sku"`
	QuantityPurchased int     `json:"amount"`
	ItemPrice         float64 `json:"item_price"`
}

ReturnItem is one line item covered by a return request.

TODO: verify against sandbox — names below follow the common v2 item naming; amounts may be strings in some regions.

type ReturnListParams added in v0.2.0 

type ReturnListParams struct {
	PageNo         int   // 1-based page number
	PageSize       int   // 1..100
	CreateTimeFrom int64 // unix seconds, inclusive; optional
	CreateTimeTo   int64 // unix seconds, inclusive; optional
	ReturnStatus   string
}

ReturnListParams are the parameters for GetReturnList.

PageNo is 1-based. The time window filters on the return's create time and is optional; when set, both bounds should be provided. ReturnStatus optionally filters by status, e.g. "REQUESTED", "PROCESSING", "ACCEPTED", "CANCELLED", "JUDGING", "CLOSED", "SELLER_DISPUTE" (exact enum values vary by region — pass through whatever the docs/console report).

type ReturnListResult added in v0.2.0 

type ReturnListResult struct {
	Return []ReturnInfo `json:"return"`
	More   bool         `json:"more"`
}

ReturnListResult is the returns/get_return_list response. Paginate by incrementing PageNo while More is true.

type ReturnProof added in v0.2.0 

type ReturnProof struct {
	PhotoList []string `json:"photo_list"`
	VideoList []string `json:"video_list"`
}

ReturnProof is one piece of evidence (photo/video) attached to a return.

TODO: verify against sandbox — the proof block shape is region-dependent; these are the commonly documented fields.

type ReturnUser added in v0.2.0 

type ReturnUser struct {
	Username string `json:"username"`
	Email    string `json:"email"`
	Portrait string `json:"portrait"`
}

ReturnUser is the buyer block attached to a return/refund request.

TODO: verify against sandbox — field set is conservative; Shopee may also expand portrait/email depending on data-masking rules.

type ShipDropoff added in v0.2.0 

type ShipDropoff struct {
	BranchID       int64  `json:"branch_id,omitempty"`
	SenderRealName string `json:"sender_real_name,omitempty"`
	TrackingNumber string `json:"tracking_number,omitempty"`
	Slug           string `json:"slug,omitempty"`
}

ShipDropoff carries the dropoff-channel parameters for ShipOrder.

type ShipOrderParams added in v0.2.0 

type ShipOrderParams struct {
	OrderSN       string
	PackageNumber string // optional, for split parcels
	Pickup        *ShipPickup
	Dropoff       *ShipDropoff
}

ShipOrderParams are the parameters for ShipOrder. Set Pickup or Dropoff according to GetShippingParameter's InfoNeeded.

type ShipPickup added in v0.2.0 

type ShipPickup struct {
	AddressID      int64  `json:"address_id,omitempty"`
	PickupTimeID   string `json:"pickup_time_id,omitempty"`
	TrackingNumber string `json:"tracking_number,omitempty"`
}

ShipPickup carries the pickup-channel parameters for ShipOrder.

type ShipmentListResult added in v0.2.0 

type ShipmentListResult struct {
	OrderList  []ShipmentOrder `json:"order_list"`
	More       bool            `json:"more"`
	NextCursor string          `json:"next_cursor"`
}

ShipmentListResult is the order/get_shipment_list response. Paginate with NextCursor while More is true.

type ShipmentOrder added in v0.2.0 

type ShipmentOrder struct {
	OrderSN       string `json:"order_sn"`
	PackageNumber string `json:"package_number"`
}

ShipmentOrder is one entry of order/get_shipment_list.

type ShippingDocumentOrder added in v0.2.0 

type ShippingDocumentOrder struct {
	OrderSN       string `json:"order_sn"`
	PackageNumber string `json:"package_number,omitempty"`
}

ShippingDocumentOrder identifies an order (or one parcel of a split order) in the shipping-document APIs. PackageNumber is only needed for split orders.

type ShippingDocumentParameter added in v0.2.0 

type ShippingDocumentParameter struct {
	OrderSN                        string   `json:"order_sn"`
	PackageNumber                  string   `json:"package_number"`
	SuggestShippingDocumentType    string   `json:"suggest_shipping_document_type"`
	SelectableShippingDocumentType []string `json:"selectable_shipping_document_type"`
	FailError                      string   `json:"fail_error"`
	FailMessage                    string   `json:"fail_message"`
}

ShippingDocumentParameter is one entry of logistics/get_shipping_document_parameter, reporting which document types may be generated for an order. SuggestShippingDocumentType is Shopee's recommendation; SelectableShippingDocumentType lists all valid choices.

type ShippingDocumentParameterResult added in v0.2.0 

type ShippingDocumentParameterResult struct {
	ResultList []ShippingDocumentParameter `json:"result_list"`
}

ShippingDocumentParameterResult is the logistics/get_shipping_document_parameter response.

type ShippingDocumentResult added in v0.2.0 

type ShippingDocumentResult struct {
	ResultList []ShippingDocumentResultEntry `json:"result_list"`
}

ShippingDocumentResult is the logistics/get_shipping_document_result response.

type ShippingDocumentResultEntry added in v0.2.0 

type ShippingDocumentResultEntry struct {
	OrderSN       string `json:"order_sn"`
	PackageNumber string `json:"package_number"`
	Status        string `json:"status"`
	FailError     string `json:"fail_error"`
	FailMessage   string `json:"fail_message"`
}

ShippingDocumentResultEntry is one entry of the logistics/get_shipping_document_result response. Status is the task state, e.g. "READY", "PROCESSING" or "FAILED".

type ShippingInfoNeeded added in v0.2.0 

type ShippingInfoNeeded struct {
	Dropoff       []string `json:"dropoff"`
	Pickup        []string `json:"pickup"`
	NonIntegrated []string `json:"non_integrated"`
}

ShippingInfoNeeded lists the field names each shipping method requires when calling ShipOrder. Use it to decide which of Pickup / Dropoff to fill in.

type ShippingParameter added in v0.2.0 

type ShippingParameter struct {
	InfoNeeded ShippingInfoNeeded `json:"info_needed"`
	Dropoff    json.RawMessage    `json:"dropoff"`
	Pickup     json.RawMessage    `json:"pickup"`
}

ShippingParameter is the order/get_shipping_parameter response. The Dropoff and Pickup blocks carry channel-specific option lists (branch / time-slot / address lists) whose shape varies by logistics channel, so they are exposed raw.

type ShopInfo 

type ShopInfo struct {
	ShopName   string `json:"shop_name"`
	Region     string `json:"region"`
	Status     string `json:"status"` // e.g. "NORMAL", "BANNED", "FROZEN"
	IsCB       bool   `json:"is_cb"`  // cross-border shop
	IsSIP      bool   `json:"is_sip"`
	MerchantID int64  `json:"merchant_id"`
	AuthTime   int64  `json:"auth_time"`   // unix seconds the shop authorized
	ExpireTime int64  `json:"expire_time"` // unix seconds the authorization expires
}

ShopInfo is a subset of the shop/get_shop_info response.

type StockFailure added in v0.2.0 

type StockFailure struct {
	ModelID      int64  `json:"model_id"`
	FailedReason string `json:"failed_reason"`
}

StockFailure is one failed entry of update_stock.

type StockSuccess added in v0.2.0 

type StockSuccess struct {
	ModelID     int64 `json:"model_id"`
	NormalStock int   `json:"normal_stock"`
}

StockSuccess is one successful entry of update_stock.

type StockUpdate added in v0.2.0 

type StockUpdate struct {
	ModelID     int64 `json:"model_id"`
	NormalStock int   `json:"normal_stock"`
}

StockUpdate sets the seller stock for a model (use ModelID 0 for an item without variations).

type TierVariation added in v0.2.0 

type TierVariation struct {
	Name       string                `json:"name"`
	OptionList []TierVariationOption `json:"option_list"`
}

TierVariation is one variation dimension of an item (for example "Color" or "Size") with its ordered list of options.

type TierVariationOption added in v0.2.0 

type TierVariationOption struct {
	Option string                    `json:"option"`
	Image  *TierVariationOptionImage `json:"image,omitempty"`
}

TierVariationOption is one option of a TierVariation. Image is optional and, when present, is shown for that option (only the first tier supports images).

type TierVariationOptionImage added in v0.2.0 

type TierVariationOptionImage struct {
	ImageID  string `json:"image_id,omitempty"`
	ImageURL string `json:"image_url,omitempty"`
}

TierVariationOptionImage is the image attached to a TierVariationOption.

type TokenResponse 

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	// ExpireIn is the number of seconds until the access token expires
	// (typically 4 hours). Refresh before then with RefreshAccessToken.
	ExpireIn int64 `json:"expire_in"`
}

TokenResponse holds the tokens returned by the auth-token endpoints.

type TrackingEvent added in v0.2.0 

type TrackingEvent struct {
	UpdateTime      int64  `json:"update_time"`
	Description     string `json:"description"`
	LogisticsStatus string `json:"logistics_status"`
}

TrackingEvent is one entry of an order's tracking history.

type TrackingInfo added in v0.2.0 

type TrackingInfo struct {
	OrderSN         string          `json:"order_sn"`
	LogisticsStatus string          `json:"logistics_status"`
	TrackingInfo    []TrackingEvent `json:"tracking_info"`
}

TrackingInfo is the logistics/get_tracking_info response.

type UnlistEntry added in v0.2.0 

type UnlistEntry struct {
	ItemID int64 `json:"item_id"`
	Unlist bool  `json:"unlist"`
}

UnlistEntry is one item to (un)list.

type UnlistFailure added in v0.2.0 

type UnlistFailure struct {
	ItemID       int64  `json:"item_id"`
	FailedReason string `json:"failed_reason"`
}

UnlistFailure is one failed entry of unlist_item.

type UnlistItemResult added in v0.2.0 

type UnlistItemResult struct {
	FailureList []UnlistFailure `json:"failure_list"`
	SuccessList []UnlistSuccess `json:"success_list"`
}

UnlistItemResult is the product/unlist_item response.

type UnlistSuccess added in v0.2.0 

type UnlistSuccess struct {
	ItemID int64 `json:"item_id"`
	Unlist bool  `json:"unlist"`
}

UnlistSuccess is one successful entry of unlist_item.

type UpdateItemParams added in v0.2.0 

type UpdateItemParams struct {
	ItemID        int64           `json:"item_id"`
	CategoryID    int64           `json:"category_id,omitempty"`
	ItemName      string          `json:"item_name,omitempty"`
	Description   string          `json:"description,omitempty"`
	ItemSKU       string          `json:"item_sku,omitempty"`
	Weight        float64         `json:"weight,omitempty"`
	Image         *ItemImage      `json:"image,omitempty"`
	LogisticInfo  []LogisticInfo  `json:"logistic_info,omitempty"`
	AttributeList []ItemAttribute `json:"attribute_list,omitempty"`
	Brand         *ItemBrand      `json:"brand,omitempty"`
	Dimension     *Dimension      `json:"dimension,omitempty"`
	Condition     string          `json:"condition,omitempty"`
	PreOrder      *ItemPreOrder   `json:"pre_order,omitempty"`
}

UpdateItemParams is the request body for UpdateItem (product/update_item).

ItemID is required; every other field is optional and is sent only when set (omitempty), so a partial update touches only the fields you provide. As with AddItemParams this models the common fields only; use UpdateItemRaw for fields not covered here.

type UpdatePriceResult added in v0.2.0 

type UpdatePriceResult struct {
	FailureList []PriceFailure `json:"failure_list"`
	SuccessList []PriceSuccess `json:"success_list"`
}

UpdatePriceResult is the product/update_price response.

type UpdateStockResult added in v0.2.0 

type UpdateStockResult struct {
	FailureList []StockFailure `json:"failure_list"`
	SuccessList []StockSuccess `json:"success_list"`
}

UpdateStockResult is the product/update_stock response.

type WalletTransaction added in v0.2.0 

type WalletTransaction struct {
	TransactionID   int64   `json:"transaction_id"`
	Status          string  `json:"status"`
	TransactionType string  `json:"transaction_type"`
	Amount          float64 `json:"amount"`
	CurrentBalance  float64 `json:"current_balance"`
	CreateTime      int64   `json:"create_time"`
	OrderSN         string  `json:"order_sn"`
	WalletType      string  `json:"wallet_type"`
	Reason          string  `json:"reason"`
}

WalletTransaction is one entry of payment/get_wallet_transaction_list.

type WalletTransactionParams added in v0.2.0 

type WalletTransactionParams struct {
	PageNo   int // 1-based; required
	PageSize int // required
	// CreateTimeFrom and CreateTimeTo bound the transaction creation time
	// (unix seconds); optional.
	CreateTimeFrom int64
	CreateTimeTo   int64
	// WalletType filters by wallet, e.g. "shopee" or "seller_balance"; empty
	// for all.
	//
	// TODO: verify the accepted wallet_type enum values against the sandbox.
	WalletType string
	// TransactionType filters by transaction type, e.g. "ORDER", "WITHDRAWAL",
	// "REFUND"; empty for all.
	//
	// TODO: verify the accepted transaction_type enum values against the
	// sandbox.
	TransactionType string
}

WalletTransactionParams are the parameters for GetWalletTransactionList. PageNo and PageSize are required; the rest are optional filters.

type WalletTransactionResult added in v0.2.0 

type WalletTransactionResult struct {
	TransactionList []WalletTransaction `json:"transaction_list"`
	More            bool                `json:"more"`
}

WalletTransactionResult is the payment/get_wallet_transaction_list response. Paginate with PageNo while More is true.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.