---
updatedAt: 2026-10-29T11:54:48.000Z
agentTools:
  projectIndex: https://docs.yotpo.com/llms.txt
---

# Retrieve order by ID

Retrieves all of the details of a specific order using its Yotpo ID.

> 👍 How to use this endpoint
>
> * Required parameters are listed below. For the full list of properties, see [About orders](https://docs.yotpo.com/reference/orders).
> * For example responses, click the relevant status code on the right.

> 📘 App partners
>
> Partner apps call this endpoint at `GET https://developers.yotpo.com/core/v3/stores/{store_id}/orders/{yotpo_order_id}`, with the access token the merchant's install gave you in the `X-Yotpo-Token` header. See [Authenticating with OAuth 2.0](https://docs.yotpo.com/docs/authenticating).

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Yotpo API V3",
    "description": "Yotpo API V3 endpoints on api.yotpo.com. Webhook events are defined separately, in webhooks.json.",
    "version": "3.0"
  },
  "servers": [
    {
      "url": "https://api.yotpo.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "X-Yotpo-Token": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Yotpo-Token",
        "description": "Your Yotpo account access token. See [Authentication](https://core-api.yotpo.com/reference/yotpo-authentication) to learn how to generate your access token."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized. The access token is missing, invalid or expired. With an invalid or expired `X-Yotpo-Token` the body is plain text: generate a new token with [Generate access token](ref:yotpo-authentication). A request with an `Authorization` header and no `X-Yotpo-Token` gets `Bad token; invalid JSON` as JSON: send the token in `X-Yotpo-Token`. An `Authorization` header sent along with a valid `X-Yotpo-Token` is ignored.",
        "content": {
          "text/plain": {
            "schema": {
              "type": "string",
              "example": "unauthorized"
            }
          },
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "description": "Error message.",
                  "example": "Bad token; invalid JSON"
                }
              }
            },
            "examples": {
              "Authorization header without X-Yotpo-Token": {
                "value": "{\n  \"message\": \"Bad token; invalid JSON\"\n}"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden. The request has no `X-Yotpo-Token` header.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "description": "Error message.",
                  "example": "Forbidden"
                }
              }
            },
            "examples": {
              "Missing token": {
                "value": "{\n  \"message\": \"Forbidden\"\n}"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "X-Yotpo-Token": []
    }
  ],
  "paths": {
    "/core/v3/stores/{store_id}/orders/{yotpo_order_id}": {
      "get": {
        "summary": "Retrieve order by ID",
        "description": "Retrieves all of the details of a specific order using its Yotpo ID.",
        "operationId": "retrieve-order-by-id",
        "parameters": [
          {
            "name": "store_id",
            "in": "path",
            "description": "The store ID (app_key).",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "yotpo_order_id",
            "in": "path",
            "description": "The Yotpo ID for the order. This ID is created automatically upon creation of the order. You can find it by using the Retrieve endpoint.",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"order\": {\n    \"yotpo_id\": 10199744826,\n    \"external_id\": \"sk34m\",\n    \"order_number\": \"sk34m\",\n    \"order_name\": \"#S53\",\n    \"order_date\": \"2021-03-25T13:57:05\",\n    \"checkout_token\": \"ll2lk3\",\n    \"payment_method\": \"visa\",\n    \"total_price\": 500.0,\n    \"subtotal_price\": 400.0,\n    \"currency\": \"USD\",\n    \"landing_site_url\": \"www.waverider.com\",\n    \"source\": \"orders_api_v3_create\",\n    \"payment_status\": \"paid\",\n    \"customer\": {\n      \"external_id\": \"ak123798684365sdfkj\",\n      \"first_name\": \"Tom\",\n      \"last_name\": \"Smith\",\n      \"email\": \"name@example.com\",\n      \"phone_number\": \"+14155550100\",\n      \"custom_properties\": {}\n    },\n    \"billing_address\": {\n      \"address1\": \"96 Coffee Street\",\n      \"address2\": \"\",\n      \"city\": \"Hudson\",\n      \"company\": \"\",\n      \"state\": \"New York\",\n      \"zip\": \"13420\",\n      \"province_code\": \"NY\",\n      \"country_code\": \"US\",\n      \"phone_number\": \"+14155550100\"\n    },\n    \"shipping_address\": {\n      \"address1\": \"96 Coffee Street\",\n      \"address2\": \"\",\n      \"city\": \"Hudson\",\n      \"company\": \"\",\n      \"state\": \"New York\",\n      \"zip\": \"13420\",\n      \"province_code\": \"NY\",\n      \"country_code\": \"US\",\n      \"phone_number\": \"+14155550100\"\n    },\n    \"custom_properties\": {\n      \"delivery_type\": \"Express\",\n      \"coupon_used\": \"true\"\n    },\n    \"fulfillments\": [\n      {\n        \"external_id\": \"4444444\",\n        \"fulfillment_date\": \"2021-03-31T11:58:51\",\n        \"status\": \"success\",\n        \"shipment_info\": {\n          \"shipment_status\": \"delivered\",\n          \"tracking_company\": \"UPS\",\n          \"tracking_url\": \"https://www.ups.com/track?tracknum=1Z999AA10123456784\",\n          \"tracking_number\": \"1Z999AA10123456784\"\n        },\n        \"fulfilled_items\": [\n          {\n            \"external_product_id\": \"23234\",\n            \"quantity\": 1\n          }\n        ]\n      }\n    ],\n    \"line_items\": [\n      {\n        \"yotpo_id\": 21568592631,\n        \"created_at\": \"2021-03-25T14:00:00\",\n        \"updated_at\": \"2021-03-25T14:00:00\",\n        \"product_id\": 1153559455,\n        \"external_product_id\": \"23234\",\n        \"quantity\": 1,\n        \"total_price\": 500.0,\n        \"subtotal_price\": 400.0,\n        \"coupon_code\": \"hg4m\",\n        \"custom_properties\": {\n          \"color\": \"blue\",\n          \"size\": \"L\"\n        }\n      }\n    ],\n    \"store_id\": \"YOUR_STORE_ID\",\n    \"created_at\": \"2021-03-25T14:00:00\",\n    \"updated_at\": \"2021-03-25T14:00:00\"\n  }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "type": "object",
                      "properties": {
                        "yotpo_id": {
                          "type": "integer",
                          "example": 12345,
                          "default": 0,
                          "description": "The Yotpo ID of the order. Use it as `yotpo_order_id` in order and fulfillment paths."
                        },
                        "external_id": {
                          "type": "string",
                          "example": "sk34m",
                          "description": "The order ID in your store, as sent when the order was created."
                        },
                        "order_name": {
                          "type": "string",
                          "example": "#S53",
                          "description": "The human-readable order name shown to the customer, for example `#S53`. Omitted when the order was created without one."
                        },
                        "order_date": {
                          "type": "string",
                          "example": "2021-03-25T13:57:05Z",
                          "description": "When the order was placed in your store (UTC, ISO 8601 without a time zone suffix)."
                        },
                        "checkout_token": {
                          "type": "string",
                          "example": "ll2lk3",
                          "description": "The ID of the checkout the order came from. Omitted when not sent."
                        },
                        "payment_method": {
                          "type": "string",
                          "example": "visa",
                          "description": "The payment method, for example `visa`. Omitted when not sent."
                        },
                        "total_price": {
                          "type": "number",
                          "example": 500,
                          "description": "The order total including discounts, shipping, taxes and tips, in `currency`."
                        },
                        "subtotal_price": {
                          "type": "number",
                          "example": 400,
                          "description": "The order price after discounts and before shipping, taxes and tips, in `currency`."
                        },
                        "currency": {
                          "type": "string",
                          "example": "USD",
                          "description": "The three-letter ISO currency code of the order, for example `USD`."
                        },
                        "landing_site_url": {
                          "type": "string",
                          "example": "www.waverider.com",
                          "description": "The URL of the page where the shopper entered your store. Omitted when not sent."
                        },
                        "payment_status": {
                          "type": "string",
                          "example": "pending",
                          "description": "The payment status of the order: `pending`, `authorized`, `partially_paid`, `paid`, `partially_refunded`, `refunded` or `voided`. Omitted when not sent."
                        },
                        "cancellation": {
                          "type": "object",
                          "properties": {
                            "cancellation_date": {
                              "type": "string",
                              "example": "2021-03-28T13:35:57Z",
                              "description": "When the order was cancelled (UTC, ISO 8601 without a time zone suffix)."
                            }
                          },
                          "description": "Cancellation details. Present only when the order was cancelled."
                        },
                        "customer": {
                          "type": "object",
                          "properties": {
                            "external_id": {
                              "type": "string",
                              "example": "ak123798684365sdfkj",
                              "description": "The customer ID in your store."
                            },
                            "email": {
                              "type": "string",
                              "example": "name@example.com",
                              "description": "The customer's email address."
                            },
                            "phone_number": {
                              "type": "string",
                              "example": "+5556251199",
                              "description": "The customer's phone number."
                            },
                            "first_name": {
                              "type": "string",
                              "example": "Tom",
                              "description": "The customer's first name."
                            },
                            "last_name": {
                              "type": "string",
                              "example": "Smith",
                              "description": "The customer's last name."
                            },
                            "accepts_sms_marketing": {
                              "type": "boolean",
                              "example": true,
                              "default": true,
                              "description": "Whether the customer accepted SMS marketing, as sent with the order. Present only when it was sent."
                            },
                            "accepts_email_marketing": {
                              "type": "boolean",
                              "example": true,
                              "default": true,
                              "description": "Whether the customer accepted email marketing, as sent with the order. Present only when it was sent."
                            },
                            "custom_properties": {
                              "type": "object",
                              "description": "Custom properties stored on the customer.",
                              "additionalProperties": {
                                "type": "string"
                              }
                            }
                          },
                          "description": "The customer who placed the order."
                        },
                        "billing_address": {
                          "type": "object",
                          "properties": {
                            "address1": {
                              "type": "string",
                              "example": "96 Coffee Street",
                              "description": "The first line of the billing address."
                            },
                            "address2": {
                              "type": "string",
                              "example": "",
                              "description": "The second line of the billing address."
                            },
                            "city": {
                              "type": "string",
                              "example": "Hudson",
                              "description": "The city of the billing address."
                            },
                            "company": {
                              "type": "string",
                              "example": "null",
                              "description": "The company name on the billing address."
                            },
                            "state": {
                              "type": "string",
                              "example": "",
                              "description": "The state or region of the billing address."
                            },
                            "zip": {
                              "type": "string",
                              "example": "13420",
                              "description": "The ZIP or postal code of the billing address."
                            },
                            "province_code": {
                              "type": "string",
                              "example": "NY",
                              "description": "The state or province code of the billing address, for example `NY`."
                            },
                            "country_code": {
                              "type": "string",
                              "example": "US",
                              "description": "The two-letter ISO country code of the billing address, for example `US`."
                            },
                            "phone_number": {
                              "type": "string",
                              "example": "+5556251199",
                              "description": "The phone number on the billing address."
                            }
                          },
                          "description": "The billing address of the order. Omitted when the order has no billing address."
                        },
                        "shipping_address": {
                          "type": "object",
                          "properties": {
                            "address1": {
                              "type": "string",
                              "example": "96 Coffee Street",
                              "description": "The first line of the shipping address."
                            },
                            "address2": {
                              "type": "string",
                              "example": "",
                              "description": "The second line of the shipping address."
                            },
                            "city": {
                              "type": "string",
                              "example": "Hudson",
                              "description": "The city of the shipping address."
                            },
                            "company": {
                              "type": "string",
                              "example": "null",
                              "description": "The company name on the shipping address."
                            },
                            "state": {
                              "type": "string",
                              "example": "",
                              "description": "The state or region of the shipping address."
                            },
                            "zip": {
                              "type": "string",
                              "example": "13420",
                              "description": "The ZIP or postal code of the shipping address."
                            },
                            "province_code": {
                              "type": "string",
                              "example": "NY",
                              "description": "The state or province code of the shipping address, for example `NY`."
                            },
                            "country_code": {
                              "type": "string",
                              "example": "US",
                              "description": "The two-letter ISO country code of the shipping address, for example `US`."
                            },
                            "phone_number": {
                              "type": "string",
                              "example": "+5556251199",
                              "description": "The phone number on the shipping address."
                            }
                          },
                          "description": "The shipping address of the order. Omitted when the order has no shipping address."
                        },
                        "customer_locale": {
                          "type": "string",
                          "example": "en-US",
                          "description": "The customer's locale when available. Currently populated for Shopify orders only and omitted from the response when null."
                        },
                        "custom_properties": {
                          "type": "object",
                          "description": "Custom properties of the order: the keys listed here, plus any customer custom properties sent through [Send aggregated order info](ref:send-aggregated-order-info), which appear with a `customer_` prefix (for example `customer_membership`).",
                          "properties": {
                            "suppress_review_request": {
                              "type": "boolean",
                              "description": "When `true`, prevents Yotpo from sending automatic review requests for this order. To suppress requests for specific products only, set this on the relevant line items instead."
                            },
                            "coupon_used": {
                              "type": "string",
                              "description": "Whether a coupon was used. Returned as a string (`\"true\"` or `\"false\"`), even though it's sent as a boolean."
                            },
                            "delivery_type": {
                              "type": "string",
                              "description": "The type of shipping or delivery used (review metadata)."
                            },
                            "customer_state": {
                              "type": "string",
                              "description": "The state the customer is located in (review metadata). Max. length: 64 characters."
                            },
                            "customer_country": {
                              "type": "string",
                              "description": "The country the customer is located in (review metadata). Must be a valid 2-character ISO code. Default value: `US`. Required if you use Google seller ratings and gather site reviews from outside the US. Max. length: 64 characters."
                            },
                            "customer_address": {
                              "type": "string",
                              "description": "The customer's home address (review metadata)."
                            },
                            "customer_phonenumber": {
                              "type": "string",
                              "description": "The customer's phone number in E.164 format (review metadata). Max. length: 64 characters."
                            },
                            "custom": {
                              "type": "string",
                              "description": "Any other information you want to link to the order (review metadata)."
                            }
                          },
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "fulfillments": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "fulfillment_date": {
                                "type": "string",
                                "example": "2021-03-31T11:58:51Z",
                                "description": "When the fulfillment was created (UTC, ISO 8601 without a time zone suffix)."
                              },
                              "status": {
                                "type": "string",
                                "example": "pending",
                                "description": "The fulfillment status: `pending`, `open`, `success`, `cancelled`, `error` or `failure`. Review requests are sent only for `success`."
                              },
                              "shipment_info": {
                                "type": "object",
                                "properties": {
                                  "shipment_status": {
                                    "type": "string",
                                    "example": "label_printed",
                                    "description": "The shipment status, for example `in_transit` or `delivered`."
                                  },
                                  "tracking_company": {
                                    "type": "string",
                                    "example": "UPS",
                                    "description": "The carrier, for example `UPS`."
                                  },
                                  "tracking_url": {
                                    "type": "string",
                                    "example": "www.ups.com/2222",
                                    "description": "The carrier's tracking page for the shipment."
                                  },
                                  "tracking_number": {
                                    "type": "string",
                                    "example": "2222",
                                    "description": "The carrier's tracking number."
                                  }
                                },
                                "description": "Shipment tracking details. Empty when none were sent."
                              },
                              "fulfilled_items": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "external_product_id": {
                                      "type": "string",
                                      "example": "23234",
                                      "description": "The product ID in your store."
                                    },
                                    "quantity": {
                                      "type": "integer",
                                      "example": 5,
                                      "default": 0,
                                      "description": "The quantity fulfilled."
                                    }
                                  }
                                },
                                "description": "The products and quantities in this fulfillment."
                              },
                              "external_id": {
                                "type": "string",
                                "description": "The fulfillment ID in your system.",
                                "example": "4444444"
                              }
                            }
                          },
                          "description": "The order's fulfillments. Empty when the order has none."
                        },
                        "line_items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "product_id": {
                                "type": "integer",
                                "example": 12345,
                                "default": 0,
                                "description": "The Yotpo ID of the product."
                              },
                              "external_product_id": {
                                "type": "string",
                                "example": "23234",
                                "description": "The product ID in your store."
                              },
                              "quantity": {
                                "type": "integer",
                                "example": 5,
                                "default": 0,
                                "description": "The quantity ordered."
                              },
                              "total_price": {
                                "type": "number",
                                "example": 500,
                                "description": "The line item total, in the order's `currency`. Omitted when not sent."
                              },
                              "subtotal_price": {
                                "type": "number",
                                "example": 400,
                                "description": "The line item price after discounts and before shipping, taxes and tips, in the order's `currency`. Omitted when not sent."
                              },
                              "coupon_code": {
                                "type": "string",
                                "example": "hg4m",
                                "description": "The coupon code applied to the line item. Omitted when not sent."
                              },
                              "custom_properties": {
                                "type": "object",
                                "description": "A key-value set of additional properties for the line item.",
                                "properties": {
                                  "suppress_review_request": {
                                    "type": "boolean",
                                    "description": "When `true`, prevents Yotpo from sending automatic review requests for this product in the order."
                                  },
                                  "color": {
                                    "type": "string",
                                    "description": "The color of the line item's product (review metadata)."
                                  },
                                  "size": {
                                    "type": "string",
                                    "description": "The size of the line item's product (review metadata)."
                                  },
                                  "vendor": {
                                    "type": "string",
                                    "description": "The vendor of the line item's product (review metadata)."
                                  },
                                  "material": {
                                    "type": "string",
                                    "description": "The material of the line item's product (review metadata)."
                                  },
                                  "model": {
                                    "type": "string",
                                    "description": "The model of the line item's product (review metadata)."
                                  },
                                  "coupon_used": {
                                    "type": "boolean",
                                    "description": "Indicates if a coupon was used in the purchase of this line item (review metadata)."
                                  },
                                  "custom": {
                                    "type": "string",
                                    "description": "Any other information you want to link to the line item (review metadata)."
                                  }
                                }
                              },
                              "yotpo_id": {
                                "type": "integer",
                                "description": "The Yotpo ID of the line item.",
                                "example": 21568592631
                              },
                              "created_at": {
                                "type": "string",
                                "description": "When the line item was created (UTC).",
                                "example": "2021-03-25T14:00:00"
                              },
                              "updated_at": {
                                "type": "string",
                                "description": "When the line item was last updated (UTC).",
                                "example": "2021-03-25T14:00:00"
                              }
                            }
                          },
                          "description": "The products in the order."
                        },
                        "order_number": {
                          "type": "string",
                          "description": "The order number. Same as `external_id` unless your platform sets one.",
                          "example": "sk34m"
                        },
                        "source": {
                          "type": "string",
                          "description": "How the order reached Yotpo, for example `orders_api_v3_create`, `orders_api_v3_update` or `register_purchase_v3`.",
                          "example": "orders_api_v3_create"
                        },
                        "store_id": {
                          "type": "string",
                          "description": "The store ID (app key).",
                          "example": "YOUR_STORE_ID"
                        },
                        "created_at": {
                          "type": "string",
                          "description": "When the order was created in Yotpo (UTC).",
                          "example": "2021-03-25T14:00:00"
                        },
                        "updated_at": {
                          "type": "string",
                          "description": "When the order was last updated in Yotpo (UTC).",
                          "example": "2021-03-25T14:00:00"
                        }
                      },
                      "description": "The order."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"errors\": [\n    {\n      \"message\": \"The request contains illegal argument/s\"\n    }\n  ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "message": {
                            "type": "string",
                            "example": "The request contains illegal argument/s",
                            "description": "What's wrong with the request, usually naming the missing or invalid field. Meant for logs; the wording can change, so don't parse it."
                          }
                        }
                      },
                      "description": "The validation errors. Usually one item."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "404",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"errors\": [\n    {\n      \"message\": \"order not found\"\n    }\n  ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "message": {
                            "type": "string",
                            "example": "order not found",
                            "description": "Says which object wasn't found. Meant for logs; the wording can change, so don't parse it."
                          }
                        }
                      },
                      "description": "The errors. Usually one item."
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "x-readme": {
          "samples-languages": [
            "http"
          ]
        }
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "value": "application/json",
        "key": "Content-Type"
      }
    ],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```

# Sibling pages

* [About orders](https://docs.yotpo.com/reference/orders.md)
* [Create order](https://docs.yotpo.com/reference/create-order.md)
* [Update order](https://docs.yotpo.com/reference/update-order.md)
* [Retrieve orders](https://docs.yotpo.com/reference/retrieve-orders.md)
* [About order fulfillments](https://docs.yotpo.com/reference/order-fulfillments.md)
* [Create order fulfillment](https://docs.yotpo.com/reference/create-order-fulfillment.md)
* [Update order fulfillment](https://docs.yotpo.com/reference/update-order-fulfillment.md)
* [Retrieve order fulfillments](https://docs.yotpo.com/reference/retrieve-order-fulfillments.md)
* [Retrieve fulfillment by ID](https://docs.yotpo.com/reference/retrieve-fulfillment-by-id.md)
* [About aggregated order info](https://docs.yotpo.com/reference/aggregated-order-info.md)
* [Send aggregated order info](https://docs.yotpo.com/reference/send-aggregated-order-info.md)