mercari shops API reference docs

GraphQL API documentation for mercari shops

API Endpoints
https://api.mercari-shops.com/v1/graphql
Headers
# Your API Personal Access Token here
Authorization: Bearer <YOUR_API_PERSONAL_ACCESS_TOKEN>

Endpoints

Production API Endpoint

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

Sandbox API Endpoint

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

Authentication

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>

User-Agent

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.

Webhook

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

We send the topic data from the following static IP addresses:

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

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

Rate limiting

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 5,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.

Changelog

2023-11-01

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

2023-07-24

2023-07-05

2023-06-23

2023-05-23

2023-05-22

2023-05-16

2023-04-18

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

2023-04-14

2023-03-28

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

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

Queries

availableProductConditionOptions

Description

Returns a list of Product Condition Option values. You can use these values for Product creation or updates

Response

Returns [ProductConditionOption!]!

Example

Query
query availableProductConditionOptions {
  availableProductConditionOptions {
    name
    type
  }
}
Response
{
  "data": {
    "availableProductConditionOptions": [
      {
        "name": "abc123",
        "type": "ALMOST_NEW"
      }
    ]
  }
}

availableProductStatusOptions

Description

Returns a list of Product Status Option values. You can use these values for Product creation or updates

Response

Returns [ProductStatusOption!]!

Example

Query
query availableProductStatusOptions {
  availableProductStatusOptions {
    name
    type
  }
}
Response
{
  "data": {
    "availableProductStatusOptions": [
      {"name": "abc123", "type": "OPENED"}
    ]
  }
}

availableShippingDurationOptions

Description

Returns a list of Shipping Duration Option values. You can use these values for Product creation or updates

Response

Returns [ShippingDurationOption!]!

Example

Query
query availableShippingDurationOptions {
  availableShippingDurationOptions {
    name
    type
  }
}
Response
{
  "data": {
    "availableShippingDurationOptions": [
      {
        "name": "xyz789",
        "type": "EIGHT_DAYS_OR_MORE_OR_UNDECIDED"
      }
    ]
  }
}

availableShippingMethodOptions

Description

Returns a list of Shipping Method Option values. You can use these values for Product creation or updates. The content of the list depends on the kind of business (BusinessKind) of a shop. Usually, 'Person' BusinessKind has fewer options than 'Sole Proprietorship' or 'Corporation'

Response

Returns [ShippingMethodOption!]!

Example

Query
query availableShippingMethodOptions {
  availableShippingMethodOptions {
    name
    type
  }
}
Response
{
  "data": {
    "availableShippingMethodOptions": [
      {"name": "abc123", "type": "COOL"}
    ]
  }
}

availableShippingPayerOptions

Description

Returns a list of Shipping Payer Option values. It represents which person will pay the shipping fee. You can use these values for Product creation or updates. Currently, you can only use SELLER value for the option

Response

Returns [ShippingPayerOption!]!

Example

Query
query availableShippingPayerOptions {
  availableShippingPayerOptions {
    name
    type
  }
}
Response
{
  "data": {
    "availableShippingPayerOptions": [
      {"name": "xyz789", "type": "SELLER"}
    ]
  }
}

cancelReasonTypes

Response

Returns [CancelReason!]!

Example

Query
query cancelReasonTypes {
  cancelReasonTypes {
    name
    type
  }
}
Response
{
  "data": {
    "cancelReasonTypes": [
      {
        "name": "xyz789",
        "type": "abc123"
      }
    ]
  }
}

errorCodes

Description

Returns a list of error codes. You might receive these error codes when your query/mutation failed

Response

Returns [ErrorCode!]!

Example

Query
query errorCodes {
  errorCodes
}
Response
{"data": {"errorCodes": ["PRODUCT_JAN_CODE_DUPLICATED"]}}

mappedProductCategories

Description

Returns a list of product category

Response

Returns [ProductCategory!]!

Arguments
Name Description
mallProductCategories - [MallProductCategory!] The List of mall product category

Example

Query
query mappedProductCategories($mallProductCategories: [MallProductCategory!]) {
  mappedProductCategories(mallProductCategories: $mallProductCategories) {
    hasChild
    id
    name
    parentId
  }
}
Variables
{"mallProductCategories": [MallProductCategory]}
Response
{
  "data": {
    "mappedProductCategories": [
      {
        "hasChild": true,
        "id": 4,
        "name": "abc123",
        "parentId": "xyz789"
      }
    ]
  }
}

order

Description

Returns an Order by ID

Response

Returns an Order!

Arguments
Name Description
id - ID! A globally-unique identifier

Example

Query
query order($id: ID!) {
  order(id: $id) {
    cancelReasonType
    canceledAt
    cancellable
    completedAt
    createdAt
    customerInfo {
      nickname
      pictureUrl
    }
    id
    messages {
      createdAt
      id
      message
      role
    }
    orderCoupon {
      couponDisplayId
      couponId
      discountAmount
    }
    paidAt
    paymentDeadline
    paymentMethod
    products {
      name
      price
      productAssetId
      productId
      variant {
        id
        janCode
        name
        skuCode
      }
    }
    salesFee
    shipping {
      id
      method
      senderAddress {
        address1
        address2
        city
        country
        firstName
        firstNameKana
        lastName
        lastNameKana
        phoneNumber
        postalCode
        state {
          ...StateFragment
        }
      }
      shippingAddress {
        address1
        address2
        city
        country
        firstName
        firstNameKana
        lastName
        lastNameKana
        phoneNumber
        postalCode
        state {
          ...StateFragment
        }
      }
      trackingCode
    }
    status
    totalPrice
    updatedAt
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "order": {
      "cancelReasonType": "DEFECTIVE_PRODUCT",
      "canceledAt": "2007-12-03T10:15:30Z",
      "cancellable": false,
      "completedAt": "2007-12-03T10:15:30Z",
      "createdAt": "2007-12-03T10:15:30Z",
      "customerInfo": UserInfo,
      "id": "4",
      "messages": [TransactionMessage],
      "orderCoupon": OrderCoupon,
      "paidAt": "2007-12-03T10:15:30Z",
      "paymentDeadline": "2007-12-03T10:15:30Z",
      "paymentMethod": ["BALANCE"],
      "products": [OrderProduct],
      "salesFee": 123,
      "shipping": Shipping,
      "status": "CANCELED",
      "totalPrice": 987,
      "updatedAt": "2007-12-03T10:15:30Z"
    }
  }
}

orders

Description

Returns a list of orders

Response

Returns an OrderConnection!

Arguments
Name Description
after - String This value is supposed to be endCursor value of PageInfo Type. You can retrieve a list that is contained after the cursor
canceled - Boolean [Deprecated] If specified, the only orders that has been canceled will be displayed. Only one of statuses or completed(canceled) should be specified. Use statuses ([CANCELED]) instead
completed - Boolean [Deprecated] If specified, the only orders that has been completed will be displayed. Only one of statuses or completed(canceled) should be specified. Use statuses ([COMPLETED]) instead
first - Int Number of the nodes that you want to get from a list. Default = 100
keyword - String If specified, the only orders that has the keyword in product name or variant name or sku code
orderedDateGte - DateTime If specified, the only orders that has the DateTime grater than equal this value will be displayed
orderedDateLt - DateTime If specified, the only orders that has the DateTime less than this value will be displayed
statuses - [OrderStatusFilter!] If specified, the only orders that have specified statuses. Only one of statuses or completed(canceled) should be specified
updatedDateGte - DateTime If specified, the only orders that updated DateTime grater than equal this value will be displayed
updatedDateLt - DateTime If specified, the only orders that updated DateTime less than this value will be displayed

Example

Query
query orders(
  $after: String,
  $canceled: Boolean,
  $completed: Boolean,
  $first: Int,
  $keyword: String,
  $orderedDateGte: DateTime,
  $orderedDateLt: DateTime,
  $statuses: [OrderStatusFilter!],
  $updatedDateGte: DateTime,
  $updatedDateLt: DateTime
) {
  orders(
    after: $after,
    canceled: $canceled,
    completed: $completed,
    first: $first,
    keyword: $keyword,
    orderedDateGte: $orderedDateGte,
    orderedDateLt: $orderedDateLt,
    statuses: $statuses,
    updatedDateGte: $updatedDateGte,
    updatedDateLt: $updatedDateLt
  ) {
    edges {
      node {
        cancelReasonType
        canceledAt
        cancellable
        completedAt
        createdAt
        customerInfo {
          ...UserInfoFragment
        }
        id
        messages {
          ...TransactionMessageFragment
        }
        orderCoupon {
          ...OrderCouponFragment
        }
        paidAt
        paymentDeadline
        paymentMethod
        products {
          ...OrderProductFragment
        }
        salesFee
        shipping {
          ...ShippingFragment
        }
        status
        totalPrice
        updatedAt
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}
Variables
{
  "after": "xyz789",
  "canceled": true,
  "completed": false,
  "first": 100,
  "keyword": "xyz789",
  "orderedDateGte": "2007-12-03T10:15:30Z",
  "orderedDateLt": "2007-12-03T10:15:30Z",
  "statuses": ["CANCELED"],
  "updatedDateGte": "2007-12-03T10:15:30Z",
  "updatedDateLt": "2007-12-03T10:15:30Z"
}
Response
{
  "data": {
    "orders": {
      "edges": [OrderEdge],
      "pageInfo": PageInfo
    }
  }
}

product

Description

Returns a Product by ID

Response

Returns a Product!

Arguments
Name Description
id - String! A globally-unique identifier

Example

Query
query product($id: String!) {
  product(id: $id) {
    assets {
      contentSize
      contentType
      id
      imageURL
    }
    brand {
      id
      name
      nameEn
    }
    categories {
      hasChild
      id
      name
      parentId
    }
    condition
    createdAt
    description
    id
    name
    price
    shippingDuration
    shippingFromState {
      id
      name
    }
    shippingMethod
    shippingPayer
    status
    updatedAt
    variants {
      id
      janCode
      name
      product {
        assets {
          ...AssetFragment
        }
        brand {
          ...ProductBrandFragment
        }
        categories {
          ...ProductCategoryFragment
        }
        condition
        createdAt
        description
        id
        name
        price
        shippingDuration
        shippingFromState {
          ...StateFragment
        }
        shippingMethod
        shippingPayer
        status
        updatedAt
        variants {
          ...ProductVariantFragment
        }
      }
      skuCode
      stockQuantity
    }
  }
}
Variables
{"id": "abc123"}
Response
{
  "data": {
    "product": {
      "assets": [Asset],
      "brand": ProductBrand,
      "categories": [ProductCategory],
      "condition": "ALMOST_NEW",
      "createdAt": "2007-12-03T10:15:30Z",
      "description": "xyz789",
      "id": "4",
      "name": "abc123",
      "price": 123,
      "shippingDuration": "EIGHT_DAYS_OR_MORE_OR_UNDECIDED",
      "shippingFromState": State,
      "shippingMethod": "COOL",
      "shippingPayer": "SELLER",
      "status": "OPENED",
      "updatedAt": "2007-12-03T10:15:30Z",
      "variants": [ProductVariant]
    }
  }
}

productBrands

Description

Returns a list of Product Brands. You can use these values for Product creation or updates

Response

Returns [ProductBrand!]!

Example

Query
query productBrands {
  productBrands {
    id
    name
    nameEn
  }
}
Response
{
  "data": {
    "productBrands": [
      {
        "id": "4",
        "name": "abc123",
        "nameEn": "abc123"
      }
    ]
  }
}

productCategories

Description

Returns a list of Product Categories. You can use these values for Product creation or updates

Response

Returns [ProductCategory!]!

Example

Query
query productCategories {
  productCategories {
    hasChild
    id
    name
    parentId
  }
}
Response
{
  "data": {
    "productCategories": [
      {
        "hasChild": false,
        "id": 4,
        "name": "abc123",
        "parentId": "xyz789"
      }
    ]
  }
}

productVariant

Description

Returns a Variant by ID or SKU code

Response

Returns a ProductVariant!

Arguments
Name Description
by - ProductVariantBy!

Example

Query
query productVariant($by: ProductVariantBy!) {
  productVariant(by: $by) {
    id
    janCode
    name
    product {
      assets {
        contentSize
        contentType
        id
        imageURL
      }
      brand {
        id
        name
        nameEn
      }
      categories {
        hasChild
        id
        name
        parentId
      }
      condition
      createdAt
      description
      id
      name
      price
      shippingDuration
      shippingFromState {
        id
        name
      }
      shippingMethod
      shippingPayer
      status
      updatedAt
      variants {
        id
        janCode
        name
        product {
          ...ProductFragment
        }
        skuCode
        stockQuantity
      }
    }
    skuCode
    stockQuantity
  }
}
Variables
{"by": ProductVariantBy}
Response
{
  "data": {
    "productVariant": {
      "id": "4",
      "janCode": "xyz789",
      "name": "abc123",
      "product": Product,
      "skuCode": "xyz789",
      "stockQuantity": 123
    }
  }
}

products

Description

Returns a list of your Shop's Products

Response

Returns a ProductConnection!

Arguments
Name Description
after - String This value is supposed to be endCursor value of PageInfo Type. You can retrieve a list that is contained after the cursor
first - Int Number of the nodes that you want to get from a list. Default = 100
keyword - String A filtering keyword to retrieve product list that is contained specified product name or sku code. Product name is searched by partial match, but sku code is searched by forward match. If you want to get a product by an exact match sku code, use productVariant query which is faster than products query

Example

Query
query products(
  $after: String,
  $first: Int,
  $keyword: String
) {
  products(
    after: $after,
    first: $first,
    keyword: $keyword
  ) {
    edges {
      node {
        assets {
          ...AssetFragment
        }
        brand {
          ...ProductBrandFragment
        }
        categories {
          ...ProductCategoryFragment
        }
        condition
        createdAt
        description
        id
        name
        price
        shippingDuration
        shippingFromState {
          ...StateFragment
        }
        shippingMethod
        shippingPayer
        status
        updatedAt
        variants {
          ...ProductVariantFragment
        }
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}
Variables
{
  "after": "abc123",
  "first": 100,
  "keyword": "abc123"
}
Response
{
  "data": {
    "products": {
      "edges": [ProductEdge],
      "pageInfo": PageInfo
    }
  }
}

shop

Description

Returns a Shop that you own

Response

Returns a Shop!

Example

Query
query shop {
  shop {
    businessKind
    createdAt
    description
    id
    name
  }
}
Response
{
  "data": {
    "shop": {
      "businessKind": "CORPORATE",
      "createdAt": "2007-12-03T10:15:30Z",
      "description": "xyz789",
      "id": 4,
      "name": "abc123"
    }
  }
}

states

Description

Returns a list of State information that includes id and State name

Response

Returns [State!]!

Example

Query
query states {
  states {
    id
    name
  }
}
Response
{
  "data": {
    "states": [{"id": 4, "name": "xyz789"}]
  }
}

webhook

Description

Returns a Webhook by ID

Response

Returns a Webhook!

Arguments
Name Description
id - ID! A globally-unique identifier

Example

Query
query webhook($id: ID!) {
  webhook(id: $id) {
    apiVersion
    createdAt
    endPoint
    id
    topic
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "webhook": {
      "apiVersion": "abc123",
      "createdAt": "2007-12-03T10:15:30Z",
      "endPoint": "xyz789",
      "id": "4",
      "topic": "ORDER_CANCELED"
    }
  }
}

webhooks

Description

Returns a list of Webhooks that is specified for your Shop

Response

Returns [Webhook!]!

Example

Query
query webhooks {
  webhooks {
    apiVersion
    createdAt
    endPoint
    id
    topic
  }
}
Response
{
  "data": {
    "webhooks": [
      {
        "apiVersion": "abc123",
        "createdAt": "2007-12-03T10:15:30Z",
        "endPoint": "xyz789",
        "id": 4,
        "topic": "ORDER_CANCELED"
      }
    ]
  }
}

Mutations

addProductVariants

Description

Adds a Variant to a Product

Response

Returns an AddProductVariantsPayload!

Arguments
Name Description
input - AddProductVariantsInput!

Example

Query
mutation addProductVariants($input: AddProductVariantsInput!) {
  addProductVariants(input: $input) {
    product {
      assets {
        contentSize
        contentType
        id
        imageURL
      }
      brand {
        id
        name
        nameEn
      }
      categories {
        hasChild
        id
        name
        parentId
      }
      condition
      createdAt
      description
      id
      name
      price
      shippingDuration
      shippingFromState {
        id
        name
      }
      shippingMethod
      shippingPayer
      status
      updatedAt
      variants {
        id
        janCode
        name
        product {
          ...ProductFragment
        }
        skuCode
        stockQuantity
      }
    }
  }
}
Variables
{"input": AddProductVariantsInput}
Response
{"data": {"addProductVariants": {"product": Product}}}

addTransactionMessage

Description

Adds a Transaction Message to an Order

Response

Returns an AddTransactionMessagePayload!

Arguments
Name Description
input - AddTransactionMessageInput!

Example

Query
mutation addTransactionMessage($input: AddTransactionMessageInput!) {
  addTransactionMessage(input: $input) {
    order {
      cancelReasonType
      canceledAt
      cancellable
      completedAt
      createdAt
      customerInfo {
        nickname
        pictureUrl
      }
      id
      messages {
        createdAt
        id
        message
        role
      }
      orderCoupon {
        couponDisplayId
        couponId
        discountAmount
      }
      paidAt
      paymentDeadline
      paymentMethod
      products {
        name
        price
        productAssetId
        productId
        variant {
          ...OrderVariantFragment
        }
      }
      salesFee
      shipping {
        id
        method
        senderAddress {
          ...ShippingAddressFragment
        }
        shippingAddress {
          ...ShippingAddressFragment
        }
        trackingCode
      }
      status
      totalPrice
      updatedAt
    }
  }
}
Variables
{"input": AddTransactionMessageInput}
Response
{"data": {"addTransactionMessage": {"order": Order}}}

cancelOrder

Description

Cancels an Order. You can not cancel completed Orders. Furthermore, you also can't do that if more than 365 days has passed since the order was created. Order cancellation is processed asynchronously. Usually, if your request is accepted correctly, the process will be done successfully in a short time. But in very rare cases, the process may take a long time. So please use order/orders query to check the exact order status if you need it

Response

Returns a CancelOrderPayload!

Arguments
Name Description
input - CancelOrderInput!

Example

Query
mutation cancelOrder($input: CancelOrderInput!) {
  cancelOrder(input: $input) {
    order {
      cancelReasonType
      canceledAt
      cancellable
      completedAt
      createdAt
      customerInfo {
        nickname
        pictureUrl
      }
      id
      messages {
        createdAt
        id
        message
        role
      }
      orderCoupon {
        couponDisplayId
        couponId
        discountAmount
      }
      paidAt
      paymentDeadline
      paymentMethod
      products {
        name
        price
        productAssetId
        productId
        variant {
          ...OrderVariantFragment
        }
      }
      salesFee
      shipping {
        id
        method
        senderAddress {
          ...ShippingAddressFragment
        }
        shippingAddress {
          ...ShippingAddressFragment
        }
        trackingCode
      }
      status
      totalPrice
      updatedAt
    }
  }
}
Variables
{"input": CancelOrderInput}
Response
{"data": {"cancelOrder": {"order": Order}}}

completeOrder

Description

Completes an Order. It notifies the buyer that the purchased product has been shipped. Sales are credited to your Shop at the same time. The order completion will be processed asynchronously. Usually, if your request is accepted correctly, the process will be done successfully in a short time. But in very rare cases, the process may take a long time. So please use order/orders query to check the exact order status if you need it

Response

Returns a CompleteOrderPayload!

Arguments
Name Description
input - CompleteOrderInput!

Example

Query
mutation completeOrder($input: CompleteOrderInput!) {
  completeOrder(input: $input) {
    order {
      cancelReasonType
      canceledAt
      cancellable
      completedAt
      createdAt
      customerInfo {
        nickname
        pictureUrl
      }
      id
      messages {
        createdAt
        id
        message
        role
      }
      orderCoupon {
        couponDisplayId
        couponId
        discountAmount
      }
      paidAt
      paymentDeadline
      paymentMethod
      products {
        name
        price
        productAssetId
        productId
        variant {
          ...OrderVariantFragment
        }
      }
      salesFee
      shipping {
        id
        method
        senderAddress {
          ...ShippingAddressFragment
        }
        shippingAddress {
          ...ShippingAddressFragment
        }
        trackingCode
      }
      status
      totalPrice
      updatedAt
    }
  }
}
Variables
{"input": CompleteOrderInput}
Response
{"data": {"completeOrder": {"order": Order}}}

createProduct

Description

Creates a Product

Response

Returns a CreateProductPayload!

Arguments
Name Description
input - CreateProductInput!

Example

Query
mutation createProduct($input: CreateProductInput!) {
  createProduct(input: $input) {
    product {
      assets {
        contentSize
        contentType
        id
        imageURL
      }
      brand {
        id
        name
        nameEn
      }
      categories {
        hasChild
        id
        name
        parentId
      }
      condition
      createdAt
      description
      id
      name
      price
      shippingDuration
      shippingFromState {
        id
        name
      }
      shippingMethod
      shippingPayer
      status
      updatedAt
      variants {
        id
        janCode
        name
        product {
          ...ProductFragment
        }
        skuCode
        stockQuantity
      }
    }
  }
}
Variables
{"input": CreateProductInput}
Response
{"data": {"createProduct": {"product": Product}}}

createWebhook

Description

Creates a Webhook for your Shop

Response

Returns a CreateWebhookPayload!

Arguments
Name Description
input - CreateWebhookInput!

Example

Query
mutation createWebhook($input: CreateWebhookInput!) {
  createWebhook(input: $input) {
    webhook {
      apiVersion
      createdAt
      endPoint
      id
      topic
    }
  }
}
Variables
{"input": CreateWebhookInput}
Response
{"data": {"createWebhook": {"webhook": Webhook}}}

debugCreateOrder

Description

Create debug order. It is a mutation for debug and test, that can only be used in a sandbox environment. In rare cases, orders may be created even if TimeoutError occurs

Response

Returns a DebugCreateOrderPayload!

Arguments
Name Description
input - DebugCreateOrderInput!

Example

Query
mutation debugCreateOrder($input: DebugCreateOrderInput!) {
  debugCreateOrder(input: $input) {
    order {
      cancelReasonType
      canceledAt
      cancellable
      completedAt
      createdAt
      customerInfo {
        nickname
        pictureUrl
      }
      id
      messages {
        createdAt
        id
        message
        role
      }
      orderCoupon {
        couponDisplayId
        couponId
        discountAmount
      }
      paidAt
      paymentDeadline
      paymentMethod
      products {
        name
        price
        productAssetId
        productId
        variant {
          ...OrderVariantFragment
        }
      }
      salesFee
      shipping {
        id
        method
        senderAddress {
          ...ShippingAddressFragment
        }
        shippingAddress {
          ...ShippingAddressFragment
        }
        trackingCode
      }
      status
      totalPrice
      updatedAt
    }
  }
}
Variables
{"input": DebugCreateOrderInput}
Response
{"data": {"debugCreateOrder": {"order": Order}}}

decreaseProductVariantStock

Description

Decreases the quantity of Stock

Arguments
Name Description
by - ProductVariantBy!
input - DecreaseProductVariantStockInput!

Example

Query
mutation decreaseProductVariantStock(
  $by: ProductVariantBy!,
  $input: DecreaseProductVariantStockInput!
) {
  decreaseProductVariantStock(
    by: $by,
    input: $input
  ) {
    productVariant {
      id
      janCode
      name
      product {
        assets {
          ...AssetFragment
        }
        brand {
          ...ProductBrandFragment
        }
        categories {
          ...ProductCategoryFragment
        }
        condition
        createdAt
        description
        id
        name
        price
        shippingDuration
        shippingFromState {
          ...StateFragment
        }
        shippingMethod
        shippingPayer
        status
        updatedAt
        variants {
          ...ProductVariantFragment
        }
      }
      skuCode
      stockQuantity
    }
  }
}
Variables
{
  "by": ProductVariantBy,
  "input": DecreaseProductVariantStockInput
}
Response
{
  "data": {
    "decreaseProductVariantStock": {
      "productVariant": ProductVariant
    }
  }
}

deleteProduct

Description

Deletes a Product

Response

Returns a DeleteProductPayload!

Arguments
Name Description
input - DeleteProductInput!

Example

Query
mutation deleteProduct($input: DeleteProductInput!) {
  deleteProduct(input: $input) {
    id
  }
}
Variables
{"input": DeleteProductInput}
Response
{"data": {"deleteProduct": {"id": "4"}}}

deleteProductVariant

Description

Deletes a Variant

Response

Returns a DeleteProductVariantPayload!

Arguments
Name Description
input - DeleteProductVariantInput!

Example

Query
mutation deleteProductVariant($input: DeleteProductVariantInput!) {
  deleteProductVariant(input: $input) {
    id
  }
}
Variables
{"input": DeleteProductVariantInput}
Response
{"data": {"deleteProductVariant": {"id": 4}}}

deleteWebhook

Description

Deletes the Webhook by ID

Response

Returns a DeleteWebhookPayload!

Arguments
Name Description
input - DeleteWebhookInput!

Example

Query
mutation deleteWebhook($input: DeleteWebhookInput!) {
  deleteWebhook(input: $input) {
    id
  }
}
Variables
{"input": DeleteWebhookInput}
Response
{"data": {"deleteWebhook": {"id": "4"}}}

increaseProductVariantStock

Description

Increases the quantity of Stock

Arguments
Name Description
by - ProductVariantBy!
input - IncreaseProductVariantStockInput!

Example

Query
mutation increaseProductVariantStock(
  $by: ProductVariantBy!,
  $input: IncreaseProductVariantStockInput!
) {
  increaseProductVariantStock(
    by: $by,
    input: $input
  ) {
    productVariant {
      id
      janCode
      name
      product {
        assets {
          ...AssetFragment
        }
        brand {
          ...ProductBrandFragment
        }
        categories {
          ...ProductCategoryFragment
        }
        condition
        createdAt
        description
        id
        name
        price
        shippingDuration
        shippingFromState {
          ...StateFragment
        }
        shippingMethod
        shippingPayer
        status
        updatedAt
        variants {
          ...ProductVariantFragment
        }
      }
      skuCode
      stockQuantity
    }
  }
}
Variables
{
  "by": ProductVariantBy,
  "input": IncreaseProductVariantStockInput
}
Response
{
  "data": {
    "increaseProductVariantStock": {
      "productVariant": ProductVariant
    }
  }
}

updateProduct

Description

Updates a Product

Response

Returns an UpdateProductPayload!

Arguments
Name Description
input - UpdateProductInput!

Example

Query
mutation updateProduct($input: UpdateProductInput!) {
  updateProduct(input: $input) {
    product {
      assets {
        contentSize
        contentType
        id
        imageURL
      }
      brand {
        id
        name
        nameEn
      }
      categories {
        hasChild
        id
        name
        parentId
      }
      condition
      createdAt
      description
      id
      name
      price
      shippingDuration
      shippingFromState {
        id
        name
      }
      shippingMethod
      shippingPayer
      status
      updatedAt
      variants {
        id
        janCode
        name
        product {
          ...ProductFragment
        }
        skuCode
        stockQuantity
      }
    }
  }
}
Variables
{"input": UpdateProductInput}
Response
{"data": {"updateProduct": {"product": Product}}}

updateProductVariant

Description

Updates a Variant

Response

Returns an UpdateProductVariantPayload!

Arguments
Name Description
by - ProductVariantBy!
input - UpdateProductVariantInput!

Example

Query
mutation updateProductVariant(
  $by: ProductVariantBy!,
  $input: UpdateProductVariantInput!
) {
  updateProductVariant(
    by: $by,
    input: $input
  ) {
    productVariant {
      id
      janCode
      name
      product {
        assets {
          ...AssetFragment
        }
        brand {
          ...ProductBrandFragment
        }
        categories {
          ...ProductCategoryFragment
        }
        condition
        createdAt
        description
        id
        name
        price
        shippingDuration
        shippingFromState {
          ...StateFragment
        }
        shippingMethod
        shippingPayer
        status
        updatedAt
        variants {
          ...ProductVariantFragment
        }
      }
      skuCode
      stockQuantity
    }
  }
}
Variables
{
  "by": ProductVariantBy,
  "input": UpdateProductVariantInput
}
Response
{
  "data": {
    "updateProductVariant": {
      "productVariant": ProductVariant
    }
  }
}

updateProductVariantSKU

Description

Updates the SKU code of the Variant

Response

Returns an UpdateProductVariantSKUPayload!

Arguments
Name Description
input - UpdateProductVariantSKUInput!

Example

Query
mutation updateProductVariantSKU($input: UpdateProductVariantSKUInput!) {
  updateProductVariantSKU(input: $input) {
    productVariant {
      id
      janCode
      name
      product {
        assets {
          ...AssetFragment
        }
        brand {
          ...ProductBrandFragment
        }
        categories {
          ...ProductCategoryFragment
        }
        condition
        createdAt
        description
        id
        name
        price
        shippingDuration
        shippingFromState {
          ...StateFragment
        }
        shippingMethod
        shippingPayer
        status
        updatedAt
        variants {
          ...ProductVariantFragment
        }
      }
      skuCode
      stockQuantity
    }
  }
}
Variables
{"input": UpdateProductVariantSKUInput}
Response
{
  "data": {
    "updateProductVariantSKU": {
      "productVariant": ProductVariant
    }
  }
}

updateProductVariants

Description

Updates multiple Variants

Response

Returns an UpdateProductVariantsPayload!

Arguments
Name Description
inputs - [UpdateProductVariantsInput!]!

Example

Query
mutation updateProductVariants($inputs: [UpdateProductVariantsInput!]!) {
  updateProductVariants(inputs: $inputs) {
    productVariants {
      id
      janCode
      name
      product {
        assets {
          ...AssetFragment
        }
        brand {
          ...ProductBrandFragment
        }
        categories {
          ...ProductCategoryFragment
        }
        condition
        createdAt
        description
        id
        name
        price
        shippingDuration
        shippingFromState {
          ...StateFragment
        }
        shippingMethod
        shippingPayer
        status
        updatedAt
        variants {
          ...ProductVariantFragment
        }
      }
      skuCode
      stockQuantity
    }
  }
}
Variables
{"inputs": [UpdateProductVariantsInput]}
Response
{
  "data": {
    "updateProductVariants": {
      "productVariants": [ProductVariant]
    }
  }
}

updateProducts

Description

Updates multiple Products. The updateProducts does not support imageUrls, so will ignore if specified in inputs

Response

Returns an UpdateProductsPayload!

Arguments
Name Description
inputs - [UpdateProductInput!]! The maximum size of the list is 20

Example

Query
mutation updateProducts($inputs: [UpdateProductInput!]!) {
  updateProducts(inputs: $inputs) {
    products {
      assets {
        contentSize
        contentType
        id
        imageURL
      }
      brand {
        id
        name
        nameEn
      }
      categories {
        hasChild
        id
        name
        parentId
      }
      condition
      createdAt
      description
      id
      name
      price
      shippingDuration
      shippingFromState {
        id
        name
      }
      shippingMethod
      shippingPayer
      status
      updatedAt
      variants {
        id
        janCode
        name
        product {
          ...ProductFragment
        }
        skuCode
        stockQuantity
      }
    }
  }
}
Variables
{"inputs": [UpdateProductInput]}
Response
{"data": {"updateProducts": {"products": [Product]}}}

updateShippingTrackingCode

Description

Updates the shipping tracking code to the order. This code is optional. But please set the shipping tracking code to make buyers find their package easily

Arguments
Name Description
input - UpdateShippingTrackingCodeInput!

Example

Query
mutation updateShippingTrackingCode($input: UpdateShippingTrackingCodeInput!) {
  updateShippingTrackingCode(input: $input) {
    order {
      cancelReasonType
      canceledAt
      cancellable
      completedAt
      createdAt
      customerInfo {
        nickname
        pictureUrl
      }
      id
      messages {
        createdAt
        id
        message
        role
      }
      orderCoupon {
        couponDisplayId
        couponId
        discountAmount
      }
      paidAt
      paymentDeadline
      paymentMethod
      products {
        name
        price
        productAssetId
        productId
        variant {
          ...OrderVariantFragment
        }
      }
      salesFee
      shipping {
        id
        method
        senderAddress {
          ...ShippingAddressFragment
        }
        shippingAddress {
          ...ShippingAddressFragment
        }
        trackingCode
      }
      status
      totalPrice
      updatedAt
    }
  }
}
Variables
{"input": UpdateShippingTrackingCodeInput}
Response
{"data": {"updateShippingTrackingCode": {"order": Order}}}

Types

AddProductVariantsInput

Fields
Input Field Description
productId - String!

The product id to add variants

variants - [ProductVariantInput!]!

The List of variants to add

Example
{
  "productId": "abc123",
  "variants": [ProductVariantInput]
}

AddProductVariantsPayload

Fields
Field Name Description
product - Product! Updated Product
Example
{"product": Product}

AddTransactionMessageInput

Fields
Input Field Description
message - String!

The message to add. The maximum length of the field is 1000 characters

orderId - ID!

The order id to add a message

Example
{
  "message": "xyz789",
  "orderId": "4"
}

AddTransactionMessagePayload

Fields
Field Name Description
order - Order! The added transaction message
Example
{"order": Order}

Asset

Description

Asset has information such as images stored in mercari shops

Fields
Field Name Description
contentSize - Int! The content-size of the asset
contentType - String! The content-type of the asset
id - ID! A globally-unique identifier
imageURL - String! The URL to access content body
Arguments
options - AssetImageOptions
Example
{
  "contentSize": 123,
  "contentType": "abc123",
  "id": "4",
  "imageURL": "abc123"
}

AssetImageOptions

Fields
Input Field Description
format - ImageForamt

The image format. jpg/png/webp

presets - [ImagePreset!]

The size preset of the image

Example
{"format": "GIF", "presets": ["Default"]}

Boolean

Description

The Boolean scalar type represents true or false

BusinessKind

Description

The possible business kind for a shop

Values
Enum Value Description

CORPORATE

Corporate. (法人)

PERSON

Person. (個人)

SOLO_PROPRIETORSHIP

Solo proprietorship. (個人事業主)

UNSPECIFIED

This value is never used
Example
"CORPORATE"

CancelOrderInput

Fields
Input Field Description
cancelReasonType - CancelReasonType!

The reason for canceling the order

id - ID!

The order id to update status

Example
{
  "cancelReasonType": "DEFECTIVE_PRODUCT",
  "id": "4"
}

CancelOrderPayload

Fields
Field Name Description
order - Order! The order cancelled
Example
{"order": Order}

CancelReason

Description

The reason why the order was canceled

Fields
Field Name Description
name - String! value of corresponds to enum
type - String! enum of cancel reason
Example
{
  "name": "xyz789",
  "type": "abc123"
}

CancelReasonType

Description

the cancel reason of the order

Values
Enum Value Description

DEFECTIVE_PRODUCT

The product is defected of the order. (商品に不備が見つかった)

NO_PAYMENT

Could not confirm the payment of the order. (支払いが確認できない)

NO_PRODUCT_STOCK

No left product stock of the order. (商品の在庫がない)

OTHERS_BY_SELLER

other reasons caused by shop. (その他(ショップ都合))

REQUEST_FROM_BUYER

Buyer requested to cancel the order. (購入者からのキャンセル依頼)

TROUBLE_BY_DELIVERY_COMPANY

Troubled by Delivery company. (配送業者によるトラブル(未着や破損))

UNSPECIFIED

This value is never used

WRONG_DELIVERY_ADDRESS

The delivery address is incorrect. (配送先住所が間違っていた)
Example
"DEFECTIVE_PRODUCT"

CompleteOrderInput

Fields
Input Field Description
id - ID!

The order id to update status

Example
{"id": "4"}

CompleteOrderPayload

Fields
Field Name Description
order - Order! The order completed
Example
{"order": Order}

CreateProductInput

Fields
Input Field Description
brandId - String

The brand id of the product. Use productBrands query to find a brandId. It shows a list of Product Brand information that includes brandId

categoryId - String!

The category id of the product. Use productCategories query to find a categoryId. It shows a list of Product Category information that includes categoryId. Only categories with no descendants can be specified

condition - ProductCondition!

The condition of the product

description - String!

The description of the product. The maximum length of the field is 3000 characters

imageUrls - [String!]!

The list of asset URLs. You can use only 'https' schema for the URLs. The maximum size of the list is 10

name - String!

The name of the product. The maximum length of the field is 130 characters

price - Int!

The price of the product. It must be between 300 and 9999999

shippingDuration - ShippingDuration!

The shipping duration

shippingFromStateId - String!

The area to be shipped from. Use states query to find a stateId. It shows a list of State information that includes StateId

shippingMethod - ShippingMethod!

The shipping method

shippingPayer - ShippingPayer!

Who pays for shipping, the sender or the recipient

status - ProductStatus!

The status of the product visibility

variants - [ProductVariantInput!]!

The Variants of the Product

Example
{
  "brandId": "aETNgbtnkJzdVDxn7vBZTJ",
  "categoryId": "AJysQvoxEefUHAAW4xEPnL",
  "condition": "ALMOST_NEW",
  "description": "abc123",
  "imageUrls": ["https://example.com/path/to/image.png"],
  "name": "xyz789",
  "price": 123,
  "shippingDuration": "EIGHT_DAYS_OR_MORE_OR_UNDECIDED",
  "shippingFromStateId": "jp01",
  "shippingMethod": "COOL",
  "shippingPayer": "SELLER",
  "status": "OPENED",
  "variants": [ProductVariantInput]
}

CreateProductPayload

Fields
Field Name Description
product - Product! The product created
Example
{"product": Product}

CreateWebhookInput

Fields
Input Field Description
endPoint - String!

The endPoint to handle the webhook topic

topic - WebhookTopic!

The topic you want to receive the event in the endpoint

Example
{"endPoint": "https://example.com/", "topic": "ORDER_CANCELED"}

CreateWebhookPayload

Fields
Field Name Description
webhook - Webhook! The webhook created
Example
{"webhook": Webhook}

CreditCardPayMethodType

Description

The possible payment methods

Values
Enum Value Description

INSTALLMENTS

Installments (分割払い)

ONETIME

One Time (一括払い)

UNRECOGNIZED

This value is not used

UNSPECIFIED

This value is not used
Example
"INSTALLMENTS"

DateTime

Description

A date-time string at UTC, such as 2019-12-03T09:54:33Z, compliant with the date-time format

Example
"2007-12-03T10:15:30Z"

DebugCreateOrderInput

Fields
Input Field Description
balancePaymentMethod - PaymentMethodBalanceInput
creditCardPaymentMethod - PaymentMethodCreditCardInput

Payment method of credit card. Debug API does not require this parameter to be entered

productId - String!

Ordered product id of the order

variantId - String!

Ordered variant id of the order

Example
{
  "balancePaymentMethod": PaymentMethodBalanceInput,
  "creditCardPaymentMethod": PaymentMethodCreditCardInput,
  "productId": "abc123",
  "variantId": "abc123"
}

DebugCreateOrderPayload

Fields
Field Name Description
order - Order! The order created
Example
{"order": Order}

DecreaseProductVariantStockInput

Fields
Input Field Description
stockQuantity - Int!

The number of quantity the stock decrease

Example
{"stockQuantity": 987}

DecreaseProductVariantStockPayload

Fields
Field Name Description
productVariant - ProductVariant! Updated Variant
Example
{"productVariant": ProductVariant}

DeleteProductInput

Fields
Input Field Description
id - ID!

The id of product to delete

Example
{"id": 4}

DeleteProductPayload

Fields
Field Name Description
id - ID! A globally-unique identifier
Example
{"id": "4"}

DeleteProductVariantInput

Fields
Input Field Description
id - ID!

The id of product variant to delete

Example
{"id": 4}

DeleteProductVariantPayload

Fields
Field Name Description
id - ID! The id of the variant deleted
Example
{"id": 4}

DeleteWebhookInput

Fields
Input Field Description
id - ID!

The webhook id to delete

Example
{"id": "4"}

DeleteWebhookPayload

Fields
Field Name Description
id - ID! The id of the webhook deleted
Example
{"id": "4"}

ErrorCode

Description

The error code for global

Values
Enum Value Description

PRODUCT_JAN_CODE_DUPLICATED

janCode is already exists

PRODUCT_SKU_CODE_DUPLICATED

skuCode is already exists

PRODUCT_VARIANT_STOCK_OUT_OF_RANGE

The quantity of the stock must be greater than or equal to 0 or less than 9999
Example
"PRODUCT_JAN_CODE_DUPLICATED"

ID

Description

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID

Example
4

ImageForamt

Description

The format type of the image asset

Values
Enum Value Description

GIF

gif

JPEG

jpeg

ORIGIN

Origin

PNG

png

WEBP

webp
Example
"GIF"

ImagePreset

Description

The preset for specifying the size and shape of the image

Values
Enum Value Description

Default

Default size and shape

Large

Large

Medium

Medium

Mini

Mini

Small

Small

Square

Square

XLarge

XLarge

XMini

XMini

XSmall

XSmall

XXSmall

XXSmall
Example
"Default"

IncreaseProductVariantStockInput

Fields
Input Field Description
stockQuantity - Int!

The number of quantity the stock increase

Example
{"stockQuantity": 987}

IncreaseProductVariantStockPayload

Fields
Field Name Description
productVariant - ProductVariant! Updated Variant
Example
{"productVariant": ProductVariant}

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1

Example
987

MallProductCategory

Fields
Input Field Description
mallType - MallType!

The mall type id

productCategoryId - String!

The product category id of mall

Example
{
  "mallType": "RAKUTEN_ICHIBA",
  "productCategoryId": "abc123"
}

MallType

Description

The mall types

Values
Enum Value Description

RAKUTEN_ICHIBA

The product category id of rakuten ichiba

UNSPECIFIED

This value is never used

YAHOO_AUCTION

The product category id of yahoo auction

YAHOO_SHOPPING

The product category id of yahoo shopping
Example
"RAKUTEN_ICHIBA"

Order

Description

Order is a customer's order information to purchase one or more items from a shop

Fields
Field Name Description
cancelReasonType - CancelReasonType! The reason of cancelation
canceledAt - DateTime Date and time when the Order was cancelled
cancellable - Boolean! Whether the order can be cancelled
completedAt - DateTime Date and time when the Order was completed
createdAt - DateTime! Date and time when the Order was created
customerInfo - UserInfo!
id - ID! A globally-unique identifier
messages - [TransactionMessage!]! A list of the Order's Transaction Messages
orderCoupon - OrderCoupon The coupon consumed with order
paidAt - DateTime Date and time the buyer of that order paid
paymentDeadline - DateTime The deadline of the payment
paymentMethod - [PaymentMethod!]! A list of the Order's Payment Methods that a buyer chose
products - [OrderProduct!]! A list of the Order's products
salesFee - Int! Amount of the fee
shipping - Shipping Shipping information of the Order
status - OrderStatus! The status of the order
totalPrice - Int! Total amount of the order. This field includes sales fee and shipping charges but discount amount (e.g. coupon) is not included
updatedAt - DateTime Date and time when the Order was updated
Example
{
  "cancelReasonType": "DEFECTIVE_PRODUCT",
  "canceledAt": "2007-12-03T10:15:30Z",
  "cancellable": true,
  "completedAt": "2007-12-03T10:15:30Z",
  "createdAt": "2007-12-03T10:15:30Z",
  "customerInfo": UserInfo,
  "id": 4,
  "messages": [TransactionMessage],
  "orderCoupon": OrderCoupon,
  "paidAt": "2007-12-03T10:15:30Z",
  "paymentDeadline": "2007-12-03T10:15:30Z",
  "paymentMethod": ["BALANCE"],
  "products": [OrderProduct],
  "salesFee": 123,
  "shipping": Shipping,
  "status": "CANCELED",
  "totalPrice": 987,
  "updatedAt": "2007-12-03T10:15:30Z"
}

OrderConnection

Fields
Field Name Description
edges - [OrderEdge!] A list of edges
pageInfo - PageInfo! Page information for Paging
Example
{
  "edges": [OrderEdge],
  "pageInfo": PageInfo
}

OrderCoupon

Fields
Field Name Description
couponDisplayId - String! consumed coupon id to display
couponId - String! consumed coupon id
discountAmount - Int! discount amount by coupon
Example
{
  "couponDisplayId": "xyz789",
  "couponId": "abc123",
  "discountAmount": 123
}

OrderEdge

Fields
Field Name Description
node - Order! A node
Example
{"node": Order}

OrderProduct

Description

OrderProduct is a single product of an order

Fields
Field Name Description
name - String! The product name
price - Int! The product price
productAssetId - String! The product asset ID
productId - ID! product ID
variant - OrderVariant! order ID
Example
{
  "name": "xyz789",
  "price": 987,
  "productAssetId": "xyz789",
  "productId": "4",
  "variant": OrderVariant
}

OrderStatus

Description

The transaction status of the order

Values
Enum Value Description

CANCELED

Represents the status that the order has been canceled

CANCELING

Represents the status that the order is canceling

COMPLETED

Represents the status that the order has been created and the shipping also has been completed

COMPLETING

Represents the status that the order is under processing to be completed

CREATING

Represents the status that the order is creating

UNSPECIFIED

This value is not used

WAITING_FOR_PAYMENT

Represents the status that the order has been created and waiting for the payment

WAITING_FOR_SHIPPING

Represents the status that the order has been created and waiting for the shipping
Example
"CANCELED"

OrderStatusFilter

Description

The filter for transaction status of the order

Values
Enum Value Description

CANCELED

Represents the status that the order has been canceled

CANCELING

Represents the status that the order is canceling

COMPLETED

Represents the status that the order has been created and the shipping also has been completed

COMPLETING

Represents the status that the order is under processing to be completed

WAITING_FOR_PAYMENT

Represents the status that the order has been created and waiting for the payment

WAITING_FOR_SHIPPING

Represents the status that the order has been created and waiting for the shipping
Example
"CANCELED"

OrderVariant

Fields
Field Name Description
id - ID! A globally-unique identifier
janCode - String The janCode of the variant
name - String The name of the variant
skuCode - String The skuCode of the variant
Example
{
  "id": 4,
  "janCode": "abc123",
  "name": "abc123",
  "skuCode": "xyz789"
}

PageInfo

Fields
Field Name Description
endCursor - String Would be set if 'hasNextPage' field was true. You can use this value for 'after' argument of 'product' query or 'order' query
hasNextPage - Boolean! Would be true if the list has next page
Example
{
  "endCursor": "abc123",
  "hasNextPage": false
}

PaymentMethod

Description

The possible payment methods

Values
Enum Value Description

BALANCE

Balance. (残高(売上金含む))

CARRIER_PAYMENT

Carrier Payment. (キャリア決済)

CREDIT_CARD

Credit Card. (クレジットカード)

DEFERRED

Merpay-smart-payment. (メルペイスマート払い) Cannot select in debugCreateOrder mutation

STORE_PAYMENT

Convenience store/ATM. (コンビニ/ATM払い)

UNSPECIFIED

Example
"BALANCE"

PaymentMethodBalanceInput

Fields
Input Field Description
fundsAmount - Int!
pointAmount - Int!
Example
{"fundsAmount": 987, "pointAmount": 987}

PaymentMethodCreditCardInput

Fields
Input Field Description
amount - Int!
creditCardId - String

Debug API does not require this parameter to be entered

payMethod - CreditCardPayMethodType!
payTimes - Int!

Number of credit card payments. When the payMethod is ONETIME, this value must be 1

Example
{
  "amount": 123,
  "creditCardId": "xyz789",
  "payMethod": "INSTALLMENTS",
  "payTimes": 123
}

Product

Description

The Product resource represents a product in your shop

Fields
Field Name Description
assets - [Asset!]! Returns a list of Product's Assets
brand - ProductBrand The Brand of the Product
categories - [ProductCategory!]! The Categories of the Product
condition - ProductCondition! The condition of the product
createdAt - DateTime! The Date and time when the product created
description - String! The description of the product
id - ID! A globally-unique identifier
name - String! The name of the product
price - Int! The price of the product. If the discount price was set to the Product, this value would be the discount price
shippingDuration - ShippingDuration! The shipping duration
shippingFromState - State! State where the Product is shipped from
shippingMethod - ShippingMethod! The shipping method
shippingPayer - ShippingPayer! Who pays for shipping, the sender or the recipient
status - ProductStatus! The product status. This controls visibility across all channel
updatedAt - DateTime! The Date and time when the product updated
variants - [ProductVariant!]! Returns a list of Variants that the Product has
Example
{
  "assets": [Asset],
  "brand": ProductBrand,
  "categories": [ProductCategory],
  "condition": "ALMOST_NEW",
  "createdAt": "2007-12-03T10:15:30Z",
  "description": "abc123",
  "id": "4",
  "name": "abc123",
  "price": 123,
  "shippingDuration": "EIGHT_DAYS_OR_MORE_OR_UNDECIDED",
  "shippingFromState": State,
  "shippingMethod": "COOL",
  "shippingPayer": "SELLER",
  "status": "OPENED",
  "updatedAt": "2007-12-03T10:15:30Z",
  "variants": [ProductVariant]
}

ProductBrand

Fields
Field Name Description
id - ID! A globally-unique identifier
name - String! The name of the brand
nameEn - String! The English name of the brand
Example
{
  "id": "4",
  "name": "abc123",
  "nameEn": "abc123"
}

ProductCategory

Fields
Field Name Description
hasChild - Boolean! This represents whether it has a child category. A category with hasChild true cannot be set to a product
id - ID! A globally-unique identifier
name - String! The name of the category
parentId - String The parent id of the category. This is used to build the tree structure
Example
{
  "hasChild": false,
  "id": 4,
  "name": "xyz789",
  "parentId": "xyz789"
}

ProductCondition

Description

The possible product conditions

Values
Enum Value Description

ALMOST_NEW

Almost new. (未使用に近い)

BAD

Bad. (全体的に状態が悪い)

BRAND_NEW

Brand new. (新品、未使用)

CLEAN

Clean. (目立った傷や汚れなし)

DIRTY

Dirty. (傷や汚れあり)

LITTLE_DIRTY

Little dirty. (やや傷や汚れあり)

UNSPECIFIED

This value is never used
Example
"ALMOST_NEW"

ProductConditionOption

Fields
Field Name Description
name - String! The name for the option
type - ProductCondition! The enum of the option
Example
{"name": "abc123", "type": "ALMOST_NEW"}

ProductConnection

Fields
Field Name Description
edges - [ProductEdge!] A list of edges
pageInfo - PageInfo! Page information for Paging
Example
{
  "edges": [ProductEdge],
  "pageInfo": PageInfo
}

ProductEdge

Fields
Field Name Description
node - Product! A node
Example
{"node": Product}

ProductStatus

Description

The product status to control visibility

Values
Enum Value Description

OPENED

The Product will be public for all customers. (公開)

UNOPENED

The Product will be private. The only Product owner can see it. (非公開)

UNSPECIFIED

This value is never used
Example
"OPENED"

ProductStatusOption

Fields
Field Name Description
name - String! The name for the option
type - ProductStatus! The enum of the option
Example
{"name": "abc123", "type": "OPENED"}

ProductVariant

Description

ProductVariant is a variation of a Product. One Product can have multiple ProductVariants. For example, A T-Shirt Product might have various colors like Red, Blue, and White. In this case, each type of color would be one ProductVariant

Fields
Field Name Description
id - ID! A globally-unique identifier
janCode - String The janCode of the variant
name - String The name of the Variant
product - Product! The product of the Variant
skuCode - String The skuCode of the variant
stockQuantity - Int! The quantity of the Stock
Example
{
  "id": 4,
  "janCode": "xyz789",
  "name": "xyz789",
  "product": Product,
  "skuCode": "abc123",
  "stockQuantity": 987
}

ProductVariantBy

Description

ProductVariant can be retrieved by id or skuCode. A query or mutation with ProductVariantBy specified can identify ProductVariant by id or skuCode

Fields
Input Field Description
id - ID

A global unique identifier

skuCode - ID

The skuCode of the variant

Example
{"id": 4, "skuCode": 4}

ProductVariantInput

Fields
Input Field Description
janCode - String

The jan-code of the variant. jan-code must be unique value in your Shop. The maximum length of the field is 14 characters. Only numbers, alphabetic, hyphens [-], and underscores [_] are allowed

name - String

The name of the variant. The maximum length of the field is 16 characters

skuCode - String

The sku-code of the variant. sku-code must be a unique value in your Shop. The maximum length of the field is 50 characters. Only numbers, alphabetic, hyphens [-], and underscores [_] are allowed

stockQuantity - Int

The number of stocks of the variant. The quantity of the stock will be overwritten by this value

Example
{
  "janCode": "xyz789",
  "name": "abc123",
  "skuCode": "abc123",
  "stockQuantity": 123
}

Shipping

Description

Shipping is shipping information

Fields
Field Name Description
id - ID! A globally-unique identifier
method - String! Shipping method of the shipped package. This value is one of "UNDECIDED"(出品者が手配), "COOL"(クール便), "MERCARI_SHIPPING_YAMATO"(らくらくメルカリ便), "MERCARI_SHIPPING_YAMATO_COOL_REFRIGERATED"(クールメリカリ便(冷蔵)), or "MERCARI_SHIPPING_YAMATO_COOL_FROZEN"(クールメルカリ便(冷凍))
senderAddress - ShippingAddress An address shipped from
shippingAddress - ShippingAddress Destination shipping address
trackingCode - String! The code assigned to packages when they are shipped
Example
{
  "id": "4",
  "method": "xyz789",
  "senderAddress": ShippingAddress,
  "shippingAddress": ShippingAddress,
  "trackingCode": "abc123"
}

ShippingAddress

Description

The address the user has. Users can have multiple addresses

Fields
Field Name Description
address1 - String The first line of the address. Typically the street address
address2 - String The second line of the address. Typically the number of the apartment, suite, or unit
city - String The name of the city, district, village, or town
country - String! The name of the country
firstName - String The first name of the customer
firstNameKana - String The first kana-name of the customer
lastName - String The last name of the customer
lastNameKana - String The last kana-name of the customer
phoneNumber - String A unique phone number for the customer
postalCode - String! The postal code of the address
state - State! State where the Product is shipped from
Example
{
  "address1": "xyz789",
  "address2": "xyz789",
  "city": "xyz789",
  "country": "xyz789",
  "firstName": "abc123",
  "firstNameKana": "xyz789",
  "lastName": "abc123",
  "lastNameKana": "xyz789",
  "phoneNumber": "abc123",
  "postalCode": "abc123",
  "state": State
}

ShippingDuration

Description

The possible types of shipping times

Values
Enum Value Description

EIGHT_DAYS_OR_MORE_OR_UNDECIDED

Eight to ninety days. (8〜90日で発送)

FOUR_TO_SEVEN_DAYS

Four to seven days. (4〜7日で発送)

ONE_TO_TWO_DAYS

One to two days. (1〜2日で発送)

TWO_TO_THREE_DAYS

Two to three days. (2〜3日で発送)

UNSPECIFIED

This value is never used
Example
"EIGHT_DAYS_OR_MORE_OR_UNDECIDED"

ShippingDurationOption

Fields
Field Name Description
name - String! The name for the option
type - ShippingDuration! The enum of the option
Example
{
  "name": "abc123",
  "type": "EIGHT_DAYS_OR_MORE_OR_UNDECIDED"
}

ShippingMethod

Description

The possible shipping methods

Values
Enum Value Description

COOL

Delivers their product with a shipping method that keeps refrigerated for its products. (クール便)

MERCARI_SHIPPING_YAMATO

Delivers its products with Mercari-Shipping. (らくらくメルカリ便)

MERCARI_SHIPPING_YAMATO_COOL_FROZEN

Delivers its products that must be frozen with Cool-Mercari-Shipping. (クールメルカリ便(冷凍))

MERCARI_SHIPPING_YAMATO_COOL_REFRIGERATED

Delivers its products with Cool-Mercari-Shipping. (クールメルカリ便(冷蔵))

UNDECIDED

The shipping is undecided. A Shop can choose any kind of Shipping method for their delivery. 未定(出品者が手配)

UNSPECIFIED

This value is never used
Example
"COOL"

ShippingMethodOption

Fields
Field Name Description
name - String! The name for the option
type - ShippingMethod! The enum of the option
Example
{"name": "abc123", "type": "COOL"}

ShippingPayer

Description

The possible shipping payers

Values
Enum Value Description

SELLER

The seller pays shipping fee. 送料込み(出品者負担)

UNSPECIFIED

This value is never used
Example
"SELLER"

ShippingPayerOption

Fields
Field Name Description
name - String! The name for the option
type - ShippingPayer! The enum of the option
Example
{"name": "xyz789", "type": "SELLER"}

Shop

Description

Shop represents a collection of the general settings and information about the shop

Fields
Field Name Description
businessKind - BusinessKind! Returns the business kind of the shop
createdAt - DateTime! The date and time when the shop was created
description - String! The shop's description used in shop page
id - ID! A globally-unique identifier
name - String! The shop's name
Example
{
  "businessKind": "CORPORATE",
  "createdAt": "2007-12-03T10:15:30Z",
  "description": "xyz789",
  "id": "4",
  "name": "xyz789"
}

State

Description

State is the area from which the shipment will be sent

Fields
Field Name Description
id - ID! A globally-unique identifier
name - String! The name of the state
Example
{"id": 4, "name": "abc123"}

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text

Example
"xyz789"

TransactionMessage

Description

TransactionMessage is a record of message exchanges regarding the transaction

Fields
Field Name Description
createdAt - DateTime! The Date and time when the transaction-message created
id - ID! A globally-unique identifier
message - String! A message posted by users
role - TransactionMessageAuthorRole! The role of author
Example
{
  "createdAt": "2007-12-03T10:15:30Z",
  "id": 4,
  "message": "abc123",
  "role": "BUYER"
}

TransactionMessageAuthorRole

Description

The author's role for message

Values
Enum Value Description

BUYER

A buyer sent this message

SELLER

A seller sent this message

UNSPECIFIED

This value is never used
Example
"BUYER"

UpdateProductInput

Fields
Input Field Description
brandId - String

The brand id of the product. Use productBrands query to find a brandId. It shows a list of Product Brand information that includes brandId

categoryId - String

The category id of the product. Use productCategories query to find a categoryId. It shows a list of Product Category information that includes categoryId. Only categories with no descendants can be specified

condition - ProductCondition

The condition of the product

description - String

The description of the product. The maximum length of the field is 3000 characters

id - ID!

The id of product to update

imageUrls - [String!]

The list of asset URLs. You can use only 'https' schema for the URLs. The maximum size of the list is 10

name - String

The name of the product. The maximum length of the field is 130 characters

price - Int

The price of the product. It must be between 300 and 9999999

shippingDuration - ShippingDuration

The shipping duration

shippingFromStateId - String

The area to be shipped from. Use states query to find a stateId. It shows a list of State information that includes StateId

shippingMethod - ShippingMethod

The shipping method

shippingPayer - ShippingPayer

Who pays for shipping, the sender or the recipient

status - ProductStatus

The status of the product visibility

Example
{
  "brandId": "xyz789",
  "categoryId": "xyz789",
  "condition": "ALMOST_NEW",
  "description": "abc123",
  "id": 4,
  "imageUrls": ["abc123"],
  "name": "abc123",
  "price": 123,
  "shippingDuration": "EIGHT_DAYS_OR_MORE_OR_UNDECIDED",
  "shippingFromStateId": "abc123",
  "shippingMethod": "COOL",
  "shippingPayer": "SELLER",
  "status": "OPENED"
}

UpdateProductPayload

Fields
Field Name Description
product - Product! Updated Product
Example
{"product": Product}

UpdateProductVariantInput

Fields
Input Field Description
janCode - String

The jan-code of the variant. jan-code must be unique value in your Shop. The maximum length of the field is 14 characters. Only numbers, alphabetic, hyphens [-], and underscores [_] are allowed

name - String

The name of the variant. The maximum length of the field is 16 characters

stockQuantity - Int

The number of stocks of the variant

Example
{
  "janCode": "xyz789",
  "name": "abc123",
  "stockQuantity": 123
}

UpdateProductVariantPayload

Fields
Field Name Description
productVariant - ProductVariant! Updated Variant
Example
{"productVariant": ProductVariant}

UpdateProductVariantSKUInput

Fields
Input Field Description
id - ID!

The id of the variant to update

skuCode - String!

The sku-code of the variant. sku-code must be a unique value in your Shop. The maximum length of the field is 50 characters. Only numbers, alphabetic, hyphens [-], and underscores [_] are allowed

Example
{"id": 4, "skuCode": "abc123"}

UpdateProductVariantSKUPayload

Fields
Field Name Description
productVariant - ProductVariant! The product variant updated
Example
{"productVariant": ProductVariant}

UpdateProductVariantsInput

Fields
Input Field Description
by - ProductVariantBy!

The identifier of the variant. Either id or skuCode is specified

input - UpdateProductVariantInput!

The update parameters of the variant

Example
{
  "by": ProductVariantBy,
  "input": UpdateProductVariantInput
}

UpdateProductVariantsPayload

Fields
Field Name Description
productVariants - [ProductVariant!]! The product variants updated
Example
{"productVariants": [ProductVariant]}

UpdateProductsPayload

Fields
Field Name Description
products - [Product!]! The products updated
Example
{"products": [Product]}

UpdateShippingTrackingCodeInput

Fields
Input Field Description
orderId - String!

The order id to add shipping tracking code

trackingCode - String!

The tracking code of the shipping

Example
{
  "orderId": "abc123",
  "trackingCode": "abc123"
}

UpdateShippingTrackingCodePayload

Fields
Field Name Description
order - Order! Updated Order
Example
{"order": Order}

UserInfo

Description

UserInfo represents an user information

Fields
Field Name Description
nickname - String! the nickname of the user
pictureUrl - String the picture url of the user
Example
{
  "nickname": "abc123",
  "pictureUrl": "abc123"
}

Webhook

Description

Webhook represents a per-topic webhook setting

Fields
Field Name Description
apiVersion - String! The api version of the webhook topic
createdAt - DateTime! The date and time when the webhook was created
endPoint - String! The endPoint to handle the webhook topic
id - ID! A globally-unique identifier
topic - WebhookTopic! The topic you want to receive the event in the endpoint
Example
{
  "apiVersion": "xyz789",
  "createdAt": "2007-12-03T10:15:30Z",
  "endPoint": "xyz789",
  "id": "4",
  "topic": "ORDER_CANCELED"
}

WebhookTopic

Description

The topic you want to receive the event in this endpoint

Values
Enum Value Description

ORDER_CANCELED

order_canceled topic for webhook

ORDER_CREATED

order_created topic for webhook

ORDER_PAID

order_paid topic for webhook

PRODUCT_ADMINISTRATOR_DELETED

product_admin_deleted topic for webhook

TRANSACTIONMESSAGE_CREATED

transaction_message_created topic for webhook

UNSPECIFIED

This value is never used
Example
"ORDER_CANCELED"