Production API Endpoint

https://api.mercari-shops.com/v1/graphql

Sandbox API Endpoint

https://api.mercari-shops-sandbox.com/v1/graphql

Personal API Access Token

Personal API Access Token is a token that mercari shops API identifies which shop sent a request. You can issue your Personal API Access Token on your shop administration page on mercari shops service.

Authorization Header

You need to add your Personal API Access Token into your requests.

Authorization: Bearer <YOUR_PERSONAL_API_ACCESS_TOKEN>

You must set a correct User-Agent to each request header for both development and production environment.

*We plan to restrict requests that do not specify the correct User-Agent during 2024.

User-Agent Format

<API_CLIENT_NAME>/<VERSION>

e.g., EXAMPLE_SHOP/1.0.0

• API_CLIENT_NAME: This value is assigned to each company that uses the API. Mercari send you this value at the time of contract.
• VERSION: This is a string value indicating version of your API client.
  • The format of the version number is up to you (e.g., "1.0.0", "2023-10-25", etc.). If your company assigns a version number to each system update, please set the same value to the User-Agent version number so that we can check it as well and facilitate communication when we receive inquiries.
  • If there is no specific version number to be set, please specify "0.0.0" as a fixed value.

If you have created a webhook resource by using createWebhook mutation, you can receive the topic data as JSON at the endpoint you specified.

Expected status codes

Sending topic data will be retried for several days until your endpoint returns one of the following HTTP status codes:

• 102
• 200
• 201
• 202
• 204

Static outbound IP addresses

⚠️ Deprecation Notice: The old static IP addresses listed below will be deprecated on 4th August 2025. Please update your firewall rules to use the new IP address ranges.

Old IP addresses (deprecated 2025/08/04):

• Sandbox
  • 34.85.79.96
  • 34.84.172.252
• Production
  • 34.84.173.38
  • 104.198.113.203

New IP address ranges:

Environment	Public IP addresses
Sandbox	103.123.182.32/27, 103.123.182.96/27, 103.123.182.192/27
Production	103.123.182.0/27, 103.123.182.64/27, 103.123.182.128/27, 103.123.182.160/28

Notes

• The addresses above are CIDR notation. For instance, 103.123.182.0/27 consists of 32 IP addresses from 103.123.182.0/32 to 103.123.182.31/32.
• Please allow only these IP addresses for the specified webhook endpoints to prevent receiving unexpected requests.

Topics

order_created

order_created is sent to your endpoint when a buyer purchases your product.

order_paid

order_paid is sent to your endpoint when a buyer has done their payment. This topic is NOT sent when a buyer purchases your product with the payment method which causes payment and order-creation at the same time like credit card payment.

order_canceled

order_canceled is sent to your endpoint when an order is canceled.

product_administrator_deleted

product_administrator_deleted is sent to your endpoint when an product is deleted by Mercari Shops administrator.

transactionmessage_created

transactionmessage_created is sent to your endpoint when a transactionmessage is sent to your shop by a buyer.

Payloads

order_created

key	type	nullable	description
order_id	string	No	A globally-unique identifier
shop_id	string	No	A globally-unique identifier
topic	string	No	order_created
product	OrderProduct	No	A product that a buyer purchased
paid	boolean	No	It becomes true if the payment has already been done.
created_at	string	No	The time when the order created. Its date format is RFC 3339.
paid_at (deprecated)	string	Yes	The time when the payment has been done. Its date format is RFC 3339. This field is set only when paid field is true.

order_paid

key	type	nullable	description
order_id	string	No	A globally-unique identifier
shop_id	string	No	A globally-unique identifier
topic	string	No	order_paid
product	OrderProduct	No	A product that a buyer purchased
paid_at	string	No	The time when the payment has been done. Its date format is RFC 3339.

order_canceled

key	type	nullable	description
order_id	string	No	A globally-unique identifier
shop_id	string	No	A globally-unique identifier
topic	string	No	order_canceled
product	OrderProduct	No	A product that a buyer purchased
canceled_at	string	No	The time when the order is canceled. Its date format is RFC 3339.

product_administrator_deleted

key	type	nullable	description
shop_id	string	No	A globally-unique identifier
topic	string	No	product_administrator_deleted
product	Product	No	A product that a seller registered
deleted_at	string	No	The time when the product is deleted. Its date format is RFC 3339.

transactionmessage_created

key	type	nullable	description
order_id	string	No	A globally-unique identifier. You can query order, orders to get related TransactionMessages using this value.
shop_id	string	No	A globally-unique identifier
topic	string	No	transactionmessage_created
created_at	string	No	The time when the transactionmessage is created. Its date format is RFC 3339.

Product

key	type	nullable	description
product_id	string	No	A globally-unique identifier
name	string	No	Product's name

OrderProduct

key	type	nullable	description
product_id	string	No	A globally-unique identifier
name	string	No	Product's name
price	number	No	Product's price
variant	Variant	Yes	It becomes null if the product doesn't have a variant

Variant

key	type	nullable	description
variant_id	string	No	A globally-unique identifier
name	string	No	Variant's name
sku_code	string	Yes	Variant's SKU code
jan_code	string	Yes	Variant's JAN code

The GraphQL API is rate-limited based on calculated query cost, which means you should consider the cost of requests over time, rather than the number of requests. The rate limit is 10,000 points per hour currently.

Note: The current calculation method and rate-limit are subject to change

Cost calcluation

By default, a field's cost is based on what the field returns. The cost is basically 1 cost per GraphQL field but the cost of some fields might be higher than usual.

FieldType	Cost
Union	1
Interface	1
Object	1
List	1
Scalar	0
Enum	0

Pagination queries are returned using the connection model. The connection field must specify the number of fetches in the first parameter, and the "number of fetches × children node" becomes the overall complexity of the connection.

Note: The maximum query cost per request is 2000.

The final score is calculated by following steps.

1. Calculate the query cost as explained in the previous section
2. Divide the number by 100 and round the result to get the final aggregate cost (minimum 1)

For example: If the query cost is 1001, the final score will be 10.

Note: The final consumption cost will be calculated by the system based on this score.

Headers

You can check your ratelimit's consumption with responded headers.

Header	description
X-Ratelimit-Limit	The number indicating the assigned rate limit points in an hour
X-Ratelimit-Remaining	The number indicating the remaining points you can use in this period
X-Ratelimit-Reset	The number indicating the time (seconds) before your rate limit is reset
X-RateLimit-Complexity	The number indicating the complexity of the query
X-RateLimit-Used	The number indicating the actual consumption cost you used for the query

Error

When there are no points available, the following error is returned with status code 400.

{
  "error": {
    "errors": [
      {
        "message": "too many requests",
        "extensions": {
          "code": "TOO_MANY_REQUESTS",
          "details": {
            "currentLimit": number,
            "remainingCost": number,
            "requestedCost": number
           }
        }
      }
    ]
  }
}

2025-06-04

• ProductBrand に nameKana を追加

2025-03-24

• ShippingAddress に firstNameEN, lastNameEN を追加

2024-10-16

• ShippingConfiguration に displayId を追加

2024-10-02

• Queries
  • productShippingConfiguration 新規追加
  • productShippingConfigurations 新規追加
• Types
  • CreateProductInput shippingConfigurationId を追加
  • UpdateProductInput shippingConfigurationId を追加
  • Product shippingConfiguration を追加
  • Product imageUrls を追加
  • Order buyerShippingFee を追加
  • ShippingPayer BUYER を追加
  • ShippingConfiguration 新規追加
  • ShippingConfigurationConnection 新規追加
  • ShippingConfigurationDetail 新規追加
  • ShippingConfigurationDetailDestination 新規追加
  • ShippingConfigurationEdge 新規追加
  • ShippingConfigurationType 新規追加

2024-07-09

• Rate limiting Rate limitingに関するHeaderの仕様を追加

以前の更新履歴

2024-07-04

• updateProductVariants で指定できる最大件数を記載

2024-04-01

• Rate limiting rate limit のポイント数を変更
• Rate limiting 制限に達した際に返却されるエラーを追記

2024-03-25

• ErrorCode PRODUCT_JAN_CODE_DUPLICATEDを deprecated に変更
• ProductVariantInput janCode のユニーク制約に関する記述を削除
• UpdateProductVariantInput janCode のユニーク制約に関する記述を削除

2023-11-01

• user-agent の仕様を追加

2023-09-21

• products SKU Code による検索が前方一致になる説明を追加
• products Variant name による検索に関する記述を削除

2023-08-28

• orders query の引数に、OrderStatusFilter 型の statuses フィールドを追加
• orders query の引数である completed を deprecated に変更
• orders query の引数である canceled を deprecated に変更

2023-08-07

• WebhookTopic に TRANSACTIONMESSAGE_CREATED を追加

2023-07-24

• WebhookTopic に PRODUCT_ADMINISTRATOR_DELETED を追加

2023-07-05

• order とorders query のレスポンスに、CancelReasonType を返す cancelReasonType フィールドを追加

2023-06-23

• PaymentMethod に CARRIER_PAYMENT を追加

2023-05-23

• order とorders query のレスポンスに、UserInfo を返す customerInfo フィールドを追加

2023-05-22

• order とorders query のレスポンスから、OrderStatus が CREATING のものを除外
• WebhookTopic に ORDER_CANCELED を追加

2023-05-16

• updateProducts mutation の追加
• updateProductVariants mutation の追加

2023-04-18

• ProductVariant に product フィールドを追加
• Variant ID に関して商品更新時の注意事項を更新

2023-04-14

• mappedProductCategories query の追加
• ProductVariant に商品更新時の注意事項を追記

2023-03-28

変更履歴がわかる Changelog セクションを追加しました。

これまでの変更履歴は以下の通りです。

• Order に orderCoupon フィールドを追加
• debugCreateOrder mutation の追加
• createProduct で画像の指定が誤っている際のエラーメッセージを追加
• completeOrder で発送方法にメルカリ便が指定されている際のエラーメッセージを追加