Wish Webhook API

openapi: 3.2.0
info:
  contact:
    email: partner-api@wish.com
  x-wish-dev-contact:
    assignee: kwei
    email: marketplace-external-api@contextlogic.com
  description: 'Wish Marketplace V3 API


    # General Information


    The Wish Marketplace API will be using oAuth to authenticate in order to offer better security for its users


    * Learn about oAuth here.'
  version: 3.0.65
  title: Wish Marketplace V3 Webhook API
servers:
- url: https://merchant.wish.com
  description: V3 API endpoint
security:
- OAuth2: []
tags:
- description: APIs for managing webhook subscriptions. Merchants can use webhook subscriptions to receive notifications about particular events, instead of having to make API calls periodically to check their status. Note that these APIs are for merchants, not ERPs. For ERPs, please log into merchant dashboard to update your ERP-level webhook subscription. Visit the webhook documentation to learn more.
  name: Webhook
paths:
  /api/v3/webhook/subscriptions:
    post:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
          description: successfully created a subscription
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: failed to create the subscription
      parameters:
      - $ref: '#/components/parameters/topic_id'
      - $ref: '#/components/parameters/endpoint'
      tags:
      - Webhook
      summary: Create a Subscription
      security:
      - OAuth2:
        - webhook:write
      operationId: createSubscription
      x-code-samples:
      - lang: java_unirest
        source: "HttpResponse<String> response = Unirest.post(\"https://merchant.wish.com/api/v3/webhook/subscriptions?topic_id=SOME_STRING_VALUE&endpoint=SOME_STRING_VALUE\")\n  .header(\"authorization\", \"Bearer REPLACE_BEARER_TOKEN\")\n  .asString();"
      - lang: php_curl
        source: "<?php\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n  CURLOPT_URL => \"https://merchant.wish.com/api/v3/webhook/subscriptions?topic_id=SOME_STRING_VALUE&endpoint=SOME_STRING_VALUE\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"POST\",\n  CURLOPT_HTTPHEADER => array(\n    \"authorization: Bearer REPLACE_BEARER_TOKEN\"\n  ),\n));\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}"
      - lang: javascript_jquery
        source: "var settings = {\n  \"async\": true,\n  \"crossDomain\": true,\n  \"url\": \"https://merchant.wish.com/api/v3/webhook/subscriptions?topic_id=SOME_STRING_VALUE&endpoint=SOME_STRING_VALUE\",\n  \"method\": \"POST\",\n  \"headers\": {\n    \"authorization\": \"Bearer REPLACE_BEARER_TOKEN\"\n  }\n}\n\n$.ajax(settings).done(function (response) {\n  console.log(response);\n});"
      - lang: shell_curl
        source: "curl --request POST \\\n  --url 'https://merchant.wish.com/api/v3/webhook/subscriptions?topic_id=SOME_STRING_VALUE&endpoint=SOME_STRING_VALUE' \\\n  --header 'authorization: Bearer REPLACE_BEARER_TOKEN'"
      - lang: python_requests
        source: 'import requests


          url = "https://merchant.wish.com/api/v3/webhook/subscriptions"


          querystring = {"topic_id":"SOME_STRING_VALUE","endpoint":"SOME_STRING_VALUE"}


          headers = {''authorization'': ''Bearer REPLACE_BEARER_TOKEN''}


          response = requests.request("POST", url, headers=headers, params=querystring)


          print(response.text)'
      description: Create a subscription
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSubscriptionsResponse'
          description: successfully queried for subscriptions
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: failed to query for subscriptions
      tags:
      - Webhook
      description: Get all subscriptions
      summary: List Subscriptions
      security:
      - OAuth2:
        - webhook:read
      x-code-samples:
      - lang: java_unirest
        source: "HttpResponse<String> response = Unirest.get(\"https://merchant.wish.com/api/v3/webhook/subscriptions\")\n  .header(\"authorization\", \"Bearer REPLACE_BEARER_TOKEN\")\n  .asString();"
      - lang: php_curl
        source: "<?php\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n  CURLOPT_URL => \"https://merchant.wish.com/api/v3/webhook/subscriptions\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"GET\",\n  CURLOPT_HTTPHEADER => array(\n    \"authorization: Bearer REPLACE_BEARER_TOKEN\"\n  ),\n));\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}"
      - lang: javascript_jquery
        source: "var settings = {\n  \"async\": true,\n  \"crossDomain\": true,\n  \"url\": \"https://merchant.wish.com/api/v3/webhook/subscriptions\",\n  \"method\": \"GET\",\n  \"headers\": {\n    \"authorization\": \"Bearer REPLACE_BEARER_TOKEN\"\n  }\n}\n\n$.ajax(settings).done(function (response) {\n  console.log(response);\n});"
      - lang: shell_curl
        source: "curl --request GET \\\n  --url 'https://merchant.wish.com/api/v3/webhook/subscriptions' \\\n  --header 'authorization: Bearer REPLACE_BEARER_TOKEN'"
      - lang: python_requests
        source: 'import requests


          url = "https://merchant.wish.com/api/v3/webhook/subscriptions"


          headers = {''authorization'': ''Bearer REPLACE_BEARER_TOKEN''}


          response = requests.request("GET", url, headers=headers)


          print(response.text)'
      operationId: listSubscriptions
  /api/v3/webhook/subscriptions/{id}:
    put:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
          description: successfully reactivated a subscription
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: failed to reactivate the subscription
      parameters:
      - $ref: '#/components/parameters/subscription_id'
      - $ref: '#/components/parameters/endpoint'
      - $ref: '#/components/parameters/status'
      tags:
      - Webhook
      summary: Update a Subscription
      security:
      - OAuth2:
        - webhook:write
      operationId: updateSubscription
      x-code-samples:
      - lang: java_unirest
        source: "HttpResponse<String> response = Unirest.put(\"https://merchant.wish.com/api/v3/webhook/subscriptions/{id}?endpoint=SOME_STRING_VALUE&status=SOME_STRING_VALUE\")\n  .header(\"authorization\", \"Bearer REPLACE_BEARER_TOKEN\")\n  .asString();"
      - lang: php_curl
        source: "<?php\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n  CURLOPT_URL => \"https://merchant.wish.com/api/v3/webhook/subscriptions/{id}?endpoint=SOME_STRING_VALUE&status=SOME_STRING_VALUE\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"PUT\",\n  CURLOPT_HTTPHEADER => array(\n    \"authorization: Bearer REPLACE_BEARER_TOKEN\"\n  ),\n));\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}"
      - lang: javascript_jquery
        source: "var settings = {\n  \"async\": true,\n  \"crossDomain\": true,\n  \"url\": \"https://merchant.wish.com/api/v3/webhook/subscriptions/{id}?endpoint=SOME_STRING_VALUE&status=SOME_STRING_VALUE\",\n  \"method\": \"PUT\",\n  \"headers\": {\n    \"authorization\": \"Bearer REPLACE_BEARER_TOKEN\"\n  }\n}\n\n$.ajax(settings).done(function (response) {\n  console.log(response);\n});"
      - lang: shell_curl
        source: "curl --request PUT \\\n  --url 'https://merchant.wish.com/api/v3/webhook/subscriptions/{id}?endpoint=SOME_STRING_VALUE&status=SOME_STRING_VALUE' \\\n  --header 'authorization: Bearer REPLACE_BEARER_TOKEN'"
      - lang: python_requests
        source: 'import requests


          url = "https://merchant.wish.com/api/v3/webhook/subscriptions/{id}"


          querystring = {"endpoint":"SOME_STRING_VALUE","status":"SOME_STRING_VALUE"}


          headers = {''authorization'': ''Bearer REPLACE_BEARER_TOKEN''}


          response = requests.request("PUT", url, headers=headers, params=querystring)


          print(response.text)'
      description: Update a subscription by its ID, only used for reactivate or change the endpoint for the inactive subscription. Do not update the endpoint for active subscription.
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
          description: successfully queried for a subscription
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: failed to query for the subscription
      parameters:
      - $ref: '#/components/parameters/subscription_id'
      tags:
      - Webhook
      summary: Get a Subscription
      security:
      - OAuth2:
        - webhook:read
      operationId: getSubscription
      x-code-samples:
      - lang: java_unirest
        source: "HttpResponse<String> response = Unirest.get(\"https://merchant.wish.com/api/v3/webhook/subscriptions/{id}\")\n  .header(\"authorization\", \"Bearer REPLACE_BEARER_TOKEN\")\n  .asString();"
      - lang: php_curl
        source: "<?php\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n  CURLOPT_URL => \"https://merchant.wish.com/api/v3/webhook/subscriptions/{id}\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"GET\",\n  CURLOPT_HTTPHEADER => array(\n    \"authorization: Bearer REPLACE_BEARER_TOKEN\"\n  ),\n));\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}"
      - lang: javascript_jquery
        source: "var settings = {\n  \"async\": true,\n  \"crossDomain\": true,\n  \"url\": \"https://merchant.wish.com/api/v3/webhook/subscriptions/{id}\",\n  \"method\": \"GET\",\n  \"headers\": {\n    \"authorization\": \"Bearer REPLACE_BEARER_TOKEN\"\n  }\n}\n\n$.ajax(settings).done(function (response) {\n  console.log(response);\n});"
      - lang: shell_curl
        source: "curl --request GET \\\n  --url 'https://merchant.wish.com/api/v3/webhook/subscriptions/{id}' \\\n  --header 'authorization: Bearer REPLACE_BEARER_TOKEN'"
      - lang: python_requests
        source: 'import requests


          url = "https://merchant.wish.com/api/v3/webhook/subscriptions/{id}"


          headers = {''authorization'': ''Bearer REPLACE_BEARER_TOKEN''}


          response = requests.request("GET", url, headers=headers)


          print(response.text)'
      description: Get a subscription by its ID
    delete:
      responses:
        '204':
          description: successfully deleted a subscription
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: failed to delete the subscription
      parameters:
      - $ref: '#/components/parameters/subscription_id'
      tags:
      - Webhook
      summary: Delete a Subscription
      security:
      - OAuth2:
        - webhook:write
      operationId: deleteSubscription
      x-code-samples:
      - lang: java_unirest
        source: "HttpResponse<String> response = Unirest.delete(\"https://merchant.wish.com/api/v3/webhook/subscriptions/{id}\")\n  .header(\"authorization\", \"Bearer REPLACE_BEARER_TOKEN\")\n  .asString();"
      - lang: php_curl
        source: "<?php\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n  CURLOPT_URL => \"https://merchant.wish.com/api/v3/webhook/subscriptions/{id}\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"DELETE\",\n  CURLOPT_HTTPHEADER => array(\n    \"authorization: Bearer REPLACE_BEARER_TOKEN\"\n  ),\n));\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}"
      - lang: javascript_jquery
        source: "var settings = {\n  \"async\": true,\n  \"crossDomain\": true,\n  \"url\": \"https://merchant.wish.com/api/v3/webhook/subscriptions/{id}\",\n  \"method\": \"DELETE\",\n  \"headers\": {\n    \"authorization\": \"Bearer REPLACE_BEARER_TOKEN\"\n  }\n}\n\n$.ajax(settings).done(function (response) {\n  console.log(response);\n});"
      - lang: shell_curl
        source: "curl --request DELETE \\\n  --url 'https://merchant.wish.com/api/v3/webhook/subscriptions/{id}' \\\n  --header 'authorization: Bearer REPLACE_BEARER_TOKEN'"
      - lang: python_requests
        source: 'import requests


          url = "https://merchant.wish.com/api/v3/webhook/subscriptions/{id}"


          headers = {''authorization'': ''Bearer REPLACE_BEARER_TOKEN''}


          response = requests.request("DELETE", url, headers=headers)


          print(response.text)'
      description: Delete a subscription by its ID
  /api/v3/webhook/topics:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllTopicsResponse'
          description: successfully queried for topics
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: failed to query for topics
      tags:
      - Webhook
      description: List all topics
      summary: List Topics
      security:
      - OAuth2:
        - webhook:read
      x-code-samples:
      - lang: java_unirest
        source: "HttpResponse<String> response = Unirest.get(\"https://merchant.wish.com/api/v3/webhook/topics\")\n  .header(\"authorization\", \"Bearer REPLACE_BEARER_TOKEN\")\n  .asString();"
      - lang: php_curl
        source: "<?php\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n  CURLOPT_URL => \"https://merchant.wish.com/api/v3/webhook/topics\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"GET\",\n  CURLOPT_HTTPHEADER => array(\n    \"authorization: Bearer REPLACE_BEARER_TOKEN\"\n  ),\n));\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}"
      - lang: javascript_jquery
        source: "var settings = {\n  \"async\": true,\n  \"crossDomain\": true,\n  \"url\": \"https://merchant.wish.com/api/v3/webhook/topics\",\n  \"method\": \"GET\",\n  \"headers\": {\n    \"authorization\": \"Bearer REPLACE_BEARER_TOKEN\"\n  }\n}\n\n$.ajax(settings).done(function (response) {\n  console.log(response);\n});"
      - lang: shell_curl
        source: "curl --request GET \\\n  --url 'https://merchant.wish.com/api/v3/webhook/topics' \\\n  --header 'authorization: Bearer REPLACE_BEARER_TOKEN'"
      - lang: python_requests
        source: 'import requests


          url = "https://merchant.wish.com/api/v3/webhook/topics"


          headers = {''authorization'': ''Bearer REPLACE_BEARER_TOKEN''}


          response = requests.request("GET", url, headers=headers)


          print(response.text)'
      operationId: getTopics
components:
  schemas:
    GetAllTopicsResponse:
      items:
        $ref: '#/components/schemas/Topic'
      type: array
      description: List of available topics that you can subscribe.
    Subscription:
      type: object
      properties:
        status:
          enum:
          - ACTIVE
          - INACTIVE
          type: string
          description: Whether the subscription is active
        endpoint:
          type: string
          description: Endpoint URL that Wish should send POST request to when the subscribed event happens
        id:
          readOnly: true
          type: string
          description: Subscription ID
          format: object-id
        topic_id:
          readOnly: true
          type: string
          description: The ID of the topic you subscribed to
          format: object-id
    Topic:
      type: object
      properties:
        topic_name:
          readOnly: true
          enum:
          - UNDEFINED
          - ORDER_ALL
          - ORDER_RELEASE
          - ORDER_FULFILLMENT_DEADLINE
          - ORDER_ADDRESS_CHANGE
          - ORDER_PENALTY
          - ORDER_TRACKING_UPDATE
          - ORDER_REFUND
          - ORDER_TAX
          - POLICY_PENALTY_ISSUE
          - POLICY_PENALTY_REVERSE
          - POLICY_PENALTY_CANCEL
          - TICKET_AWAITING_MERCHANT
          - PRODUCT_BOOST_CAMPAIGN_STATS_UPDATE
          - PRODUCT_BOOST_CAMPAIGN_CREATION
          - PRODUCT_BOOST_CAMPAIGN_ATTRIBUTE_UPDATE
          - PRODUCT_BOOST_CAMPAIGN_PRODUCT_STATS_UPDATE
          - PRODUCT_BOOST_CAMPAIGN_PRODUCT_LOW_PERFORMANCE
          - PRODUCT_BOOST_TRENDING_CATEGORIES
          - PRODUCT_BOOST_ACCOUNT_BALANCE_UPDATE
          - PRODUCT_UPDATE_MERCHANT
          - PRODUCT_IMAGE_JOB_STATUS_UPDATE
          - PRODUCT_TAGGING_UPDATE
          - PRODUCT_INVENTORY_CHANGE_WISH_USER
          - PRODUCT_INVENTORY_CHANGE_MERCHANT
          - PRODUCT_SOLDOUT
          type: string
          description: Type of event that triggers webhook. This will be set in the header `Wish-Topic` of the webhook message we send to you.
        id:
          readOnly: true
          type: string
          description: ID of the topic
          format: object-id
        api_version:
          readOnly: true
          enum:
          - V3
          type: string
          description: The Wish API version used to serialize webhook events. This will be set in the header `Wish-API-Version` of the webhook message we send to you.
    ListSubscriptionsResponse:
      items:
        $ref: '#/components/schemas/Subscription'
      type: array
      description: List of subscriptions returned.
    APIError:
      required:
      - code
      - message
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
          format: int32
  parameters:
    subscription_id:
      schema:
        type: string
        format: object-id
      required: true
      description: ID of the subscription
      name: id
      in: path
    endpoint:
      schema:
        type: string
      required: false
      description: Endpoint URL that Wish should send POST request to when the subscribed event happens
      name: endpoint
      in: query
    status:
      schema:
        enum:
        - ACTIVE
        type: string
      required: false
      description: Whether the subscription is active
      name: status
      in: query
    topic_id:
      schema:
        type: string
        format: object-id
      required: false
      description: ID of the topic, obtained from the [getTopics API](/documentation/api/v3/reference#operation/getTopics)
      name: topic_id
      in: query
  securitySchemes:
    OpenID:
      type: openIdConnect
      openIdConnectUrl: https://merchant.wish.com/oidc/.well-known/openid-configuration
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            payments:write: Update payments
            tickets:write: Write customer tickets
            epc:read: read EPC info
            returns:write: Write returns
            returns:read: Read returns
            fbw:read: Read FBW
            products:read: Read products
            payments:read: Read payments
            fbw:write: Write FBW
            merchant:write: Write merchant
            products:write: Write products
            ratings:read: Read ratings
            videos:read: Read videos
            compliance:write: Write Compliance
            product_boost:read: Read ProductBoost
            listing_quality:read: Read listing quality
            webhook:write: Write webhook
            orders:read: Read orders
            compliance:read: Read Compliance
            fbs:read: Read FBS
            penalties:read: Read penalties
            penalties:write: Update penalties
            infractions:read: Read infractions
            orders:write: Update orders
            merchant:read: Read merchant
            notifications:write: Write notifications
            announcements:read: Read announcements
            product_boost:write: Write ProductBoost
            notifications:read: Read notifications
            webhook:read: Read webhook
            qoo10:read: Read Qoo10
            wps_parcel:write: Write WishParcel
            wps_parcel:read: Read WishParcel
            tickets:read: Read customer tickets
            infractions:write: Write infractions
            videos:write: Write videos
            epc:write: write EPC info
          tokenUrl: https://merchant.wish.com/api/v3/oauth/access_token
          refreshUrl: https://merchant.wish.com/api/v3/oauth/refresh_token
          authorizationUrl: https://merchant.wish.com/v3/oauth/authorize
externalDocs:
  url: https://merchant.wish.com/documentation/api/v3/explorer
  description: API explorer
x-wish-hidden: false