Yelp Checkout API

openapi: 3.2.0
info:
  title: Checkout API
  version: '1.0'
servers:
- url: https://partner-api.yelp.com/checkout
security:
- basic: []
tags:
- name: Checkout API
paths:
  /opportunities/{opportunity_id}/v3:
    get:
      tags:
      - Checkout API
      summary: Get Opportunity
      operationId: get_opportunity
      description: 'Get info that user provided (e.g. customer address) when they were checking if business can service them (e.g. business delivers to their address or has a reservation time slot).


        The `opportunity_id` is provided to the Partner via the iframe URL and is the same token provided to the Partner when Yelp POSTs the user''s customer address to check for delivery availability. This call is optional if the Partner temporarily caches the customer_address and opportunity token during the delivery availability check.


        See Opportunity resource for more info.'
      parameters:
      - name: opportunity_id
        in: path
        required: true
        description: Unique identifier for this Opportunity
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved the opportunity.
          content:
            application/json:
              examples:
                Result:
                  value:
                    opportunity_id: unique identifier for this Opportunity
                    partner_business_id: '1234'
                    request_time: 1544466453
                    service_type: food
                    selected_option: at_customer
                    availability_constraints:
                    - object: CustomerAddressConstraint
                      customer_address_str: 123 Main St., SF, 94102
                      customer_address:
                        object: Address
                        address1: 123 Main St.
                        city: San Francisco
                        postal_code: '94102'
              schema:
                type: object
                properties:
                  opportunity_id:
                    type: string
                  partner_business_id:
                    type: string
                  request_time:
                    type: integer
                  service_type:
                    type: string
                  selected_option:
                    type: string
                  availability_constraints:
                    type: array
                    items:
                      type: object
                      properties:
                        object:
                          type: string
                        customer_address_str:
                          type: string
                        customer_address:
                          type: object
                          properties:
                            object:
                              type: string
                            address1:
                              type: string
                            city:
                              type: string
                            postal_code:
                              type: string
  /orders/create/v3:
    post:
      tags:
      - Checkout API
      summary: Create Order
      operationId: create_order
      description: 'This creates a Yelp Checkout Order and is to be called after the user builds and submits his/her order on the iframe. This call returns a `yelp_order_id`.


        In other words, the iframe POST goes to the Partner server, where the user''s request can be processed however necessary by the Partner. Immediately following this, the Partner must POST to the above URL to communicate to Yelp the details of the Order. In return, Yelp will give the Partner a yelp_order_id.


        See Order resource for more info.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - object
              - notification_url
              - opportunity_id
              properties:
                order:
                  description: See [Order Resource](https://docs.developer.yelp.com/docs/resources#section-order)
                  type: object
                notification_url:
                  description: HTTPS URL to which Yelp shall POST OrderStatus updates - e.g. when charge processing is completed
                  type: string
                opportunity_id:
                  description: token that Yelp passed to partner via iframe and when checking availability of business
                  type: string
      responses:
        '200':
          description: Successfully created an order.
          content:
            application/json:
              examples:
                Result:
                  value:
                    yelp_order_id: e6efe441eb9aa321bab01bc28d9149ff
              schema:
                type: object
                properties:
                  yelp_order_id:
                    type: string
        '400':
          description: "This error is returned in any of the following scenarios:\n\n| Status  |\terror_code                     | error_message (example)\n| ------- | -------------------------------- | ------------------------------\n| 400     | UNREGISTERED_PARTNER_BUSINESS_ID | The partner business id specified is not mapped to a known Yelp business id\n"
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '403':
          description: "This error is returned in any of the following scenarios:\n\n| Status  |\terror_code   | error_message (example)\n| ------- | -------------- | ------------------------------\n| 403     | UNAUTHORIZED   | Partner is not enabled for V3 API flow\n"
          content:
            application/json:
              $ref: '#/paths/~1orders~1create~1v3/post/responses/400/content/application~1json'
        '412':
          description: "This error is returned in any of the following scenarios:\n\n| Status  |\terror_code            | error_message (example)\n| ------- | ----------------------- | ------------------------------\n| 412     | CURRENCY_MISMATCH_ERROR | Currency mismatch with partner contract\n"
          content:
            application/json:
              $ref: '#/paths/~1orders~1create~1v3/post/responses/400/content/application~1json'
  /orders/{yelp_order_id}/cancel/v3:
    post:
      tags:
      - Checkout API
      summary: Cancel Order
      operationId: cancel_order
      description: 'Cancel a Yelp Checkout Order.


        This can be called anytime after an order is created. Any associated credit card auths will be cancelled, and any charges refunded. The order will transition into a cancelled state and no further actions can be performed on the order.


        Like `/update`, this operation is asynchronous as well. That is, after passing basic sanity checks, it immediately returns an HTTP 200 response that includes the `yelp_order_id` and an `order_request_id`, which will later be included as part of the partner notification that will notify the partner of the success or failure of the cancel request.


        Any amount that has been collected by Yelp minus the `cancellation_fee` will be refunded to the user before the Order transitions to the cancelled state. This implies that Yelp may charge the user credit card if the amount thus far collected is not sufficient to cover the `cancellation_fee`.


        The Partner should call `/cancel` whenever the Order becomes invalid, for instance:

        * when user cancels the Order via Partner or business

        * when the Order can not be fulfilled because business closed or depleted inventory

        * when the reservation timeslot is no longer available

        * when user cancels through Yelp and a cancellation policy applies, the order will transition to a temporary state and await to go to `CANCEL_PENDING`


        The partner must call `/cancel` to bring the order to a canceled state and charge/refund CC if needed:

        * when business through the partner reports a "no show" for an appointment.


        The Partner may specify a cancellation fee if the user needs to pay to cancel the order.


        Orders that have stayed in the "pending_user_submit" state for longer than two weeks will be auto-cancelled by Yelp.


        Although the request body only contains optional fields, the body itself MUST both be sent and be valid JSON. If you wish to specify none of the optional request arguments, simply encode an empty JSON object.


        ## cancellation_fee

        This is the net amount that Yelp is to charge the user for cancelling this order. Yelp will ensure that the specified amount is ultimately charged to the user (assuming we can collect on the CC). Here are some examples for illustration:


        CC hold case, cancellation fee $0 - the business owner does not wish to charge a fee


        CC hold case, cancellation fee $100 - the business owner wants to charge $100 for cancellation


        Deposit $100, cancellation fee $0 - the business owner does not wish to charge a fee, so Yelp will refund the $100


        Deposit $100, cancellation fee $100 - the business owner wishes to retain the deposit, Yelp does not need to do anything wrt to CC charges, just bring the order to CANCELLED state.


        Deposit $100, cancellation fee $25 - the business owner only wishes to charge $25 for the cancellation, so yelp will refund $75 back to CC'
      parameters:
      - $ref: '#/paths/~1orders~1{yelp_order_id}~1update~1v3/put/parameters/0'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cancellation_fee:
                  description: Cancellation fee, see [below](https://docs.developer.yelp.com/reference/cancel_order#cancellation_fee)
                  type: object
                reason:
                  description: Explanation of why order was cancelled
                  type: string
                cancellation_scenario:
                  description: Refers to a fixed set of scenarios for the cancellation. See [CancellationScenarioEnum](https://docs.developer.yelp.com/docs/resources#cancellationscenario-enum) for details. If missing, then we assume `cancel_by_partner`
                  type: object
      responses:
        '200':
          description: Successfully started the asynchronous process of deleting an order.
          content:
            application/json:
              examples:
                Result:
                  value:
                    yelp_order_id: e6efe441eb9aa321bab01bc28d9149ff
                    order_request_id: abc123
              schema:
                type: object
                properties:
                  yelp_order_id:
                    type: string
                  order_request_id:
                    type: string
        '403':
          $ref: '#/paths/~1orders~1create~1v3/post/responses/403'
        '422':
          $ref: '#/paths/~1orders~1{yelp_order_id}~1update~1v3/put/responses/422'
        '423':
          $ref: '#/paths/~1orders~1{yelp_order_id}~1update~1v3/put/responses/423'
  /orders/{yelp_order_id}/confirmation_status/v3:
    post:
      tags:
      - Checkout API
      summary: Update Order Status
      operationId: update_order_status
      description: '**This API is only for specific food partners.**


        This allows a status update to an order. This call returns a status code which indicates if the request was successful.


        A notification will not be sent in the following scenarios:

        * The order was made over 3 hours ago

        * The same notification (same `yelp_order_id` and the `confirmation_type`) has already been sent

        * An ETA is provided and the notification is being sent past the ETA

        * An `order_confirmed` update is trying to be sent after a `deliver_in_progress` notification'
      parameters:
      - $ref: '#/paths/~1orders~1{yelp_order_id}~1update~1v3/put/parameters/0'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - confirmation_type
              - eta_in_minutes
              properties:
                confirmation_type:
                  description: '[ConfirmationType](https://docs.developer.yelp.com/docs/resources#confirmationtype-enum) enum. The state the order is being updated to.'
                  type: object
                eta_in_minutes:
                  description: The estimated time of arrival.
                  type: integer
      responses:
        '200':
          description: Successfully updated the order status.
          content:
            application/json:
              schema:
                type: object
                properties: {}
              examples:
                Result:
                  value: {}
        '403':
          description: "This error is returned in any of the following scenarios:\n\n| Status  |\terror_code          | error_message (example)\n| ------- | --------------------- | ------------------------------\n| 403     | ORDER_STATE_INVALID   | Order is in an invalid state to perform this operation.\n"
          content:
            application/json:
              $ref: '#/paths/~1orders~1create~1v3/post/responses/400/content/application~1json'
  /orders/{yelp_order_id}/notifications/v3:
    get:
      tags:
      - Checkout API
      summary: Get Status Change Notifications
      operationId: get_status_change_notifications
      description: 'Get status change notifications associated with a Yelp Checkout Order, ordered by most recent first.


        See OrderStatusNotification resource for more info.'
      parameters:
      - $ref: '#/paths/~1orders~1{yelp_order_id}~1update~1v3/put/parameters/0'
      - name: offset
        in: query
        required: false
        description: Pagination offset
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        required: false
        description: Pagination limit
        schema:
          type: integer
          default: 100
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Successfully retrieved order status notifications.
          content:
            application/json:
              examples:
                Result:
                  value:
                    offset: 100
                    total_count: 125
                    notifications:
                    - notification_id: 088c7c477ee66436f6e656c5740576f2
                      yelp_order_id: e6efe441eb9aa321bab01bc28d9149ff
                      order_request_id: abc123
                      time_created: 1544465045
                      order_status: charge_pending
                    - notification_id: 088c7c477ee66436f6e656c5740576f2
                      yelp_order_id: e6efe441eb9aa321bab01bc28d9149ff
                      order_request_id: abc123
                      time_created: 1544465047
                      order_status": cancelled
              schema:
                type: object
                properties:
                  offset:
                    type: integer
                  total_count:
                    type: integer
                  notifications:
                    type: array
                    items:
                      type: object
                      properties:
                        notification_id:
                          type: string
                        yelp_order_id:
                          type: string
                        order_request_id:
                          type: string
                        time_created:
                          type: integer
                        order_status:
                          type: string
  /orders/{yelp_order_id}/status/v3:
    get:
      tags:
      - Checkout API
      summary: Get Order Status
      operationId: get_order_status
      description: 'Get the status of a Yelp Checkout Order.


        Partner Server is free to poll the status of an order at any time. It will also be provided as part of the `OrderStatusChangeNotification`.


        See OrderStatus resource for more info.'
      parameters:
      - $ref: '#/paths/~1orders~1{yelp_order_id}~1update~1v3/put/parameters/0'
      responses:
        '200':
          description: Successfully retrieved the order status.
          content:
            application/json:
              examples:
                Result:
                  value:
                    yelp_order_id: e6efe441eb9aa321bab01bc28d9149ff
                    order_status: ready_for_fulfillment
                    time_created: '1544464522'
                    time_updated: '1544464523'
              schema:
                type: object
                properties:
                  yelp_order_id:
                    type: string
                  order_status:
                    type: string
                  time_created:
                    type: string
                  time_updated:
                    type: string
  /orders/{yelp_order_id}/update/v3:
    put:
      tags:
      - Checkout API
      summary: Update Order
      operationId: update_order
      description: 'Update an existing Yelp Checkout Order by passing a Order object as the Partner wishes it to be.


        Fields that cannot be updated: `yelp_order_id`, `service`, `billing_type`, `partner_business_id`, `collection_type`. These must be included as part of the Order object, but should match those passed when the order was created.


        This operation is asynchronous, in that only basic sanity checking is done at the time the update request is submitted to Yelp, and, barring failure of those, the operation immediately returns an HTTP 200 response that includes the `yelp_order_id` and an `order_request_id`, which is a unique identifier for this partner request. Once submitted, Yelp will attempt to process this update request, including re-examining transactions associated with the order. The final success or failure of the operation is then delivered to the Partner by POSTing an `OrderStatusChangeNotification` to the `notification_url` provided at order creation time. This notification will include the matching `order_request_id` given to the Partner when the request was submitted.


        A Yelp Checkout Order may be updated before and after charges are made. However, only one update request may be outstanding at a time. That is, a Partner cannot submit a second update request before an `OrderStatusChangeNotification` is received for the first.


        On every update call, all transactions on the Order are re-examined and possibly cancelled or replaced by up-to-date transactions.


        See Order resource for more info.'
      parameters:
      - name: yelp_order_id
        description: ID of order that Yelp will try to update.
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                order:
                  description: Current complete (not a diff) Order as it should be after updates. See [Order Resource](https://docs.developer.yelp.com/docs/resources#section-order)
                  type: object
      responses:
        '200':
          description: Successfully started the asynchronous process of updating an order.
          content:
            application/json:
              examples:
                Result:
                  value:
                    yelp_order_id: e6efe441eb9aa321bab01bc28d9149ff
                    order_request_id: abc123
              schema:
                type: object
                properties:
                  yelp_order_id:
                    type: string
                  order_request_id:
                    type: string
        '403':
          $ref: '#/paths/~1orders~1create~1v3/post/responses/403'
        '422':
          description: "This error is returned in any of the following scenarios:\n\n| Status  | error_code                      | error_message (example)\n| ------- | ------------------------------- | ------------------------------\n| 422     | INVALID_ORDER_OPERATION\t      | The order cannot be updated (either because it is cancelled or because another partner request is being processed)\n| 422\t    | COLLECTION_TYPE_MUST_BE_PREPAID |\tIf the collection_type is passed as something other than `prepaid`\n"
          content:
            application/json:
              $ref: '#/paths/~1orders~1create~1v3/post/responses/400/content/application~1json'
        '423':
          description: "This error is returned in any of the following scenarios:\n\n| Status  | error_code                      | error_message (example)\n| ------- | ------------------------------- | ------------------------------\n| 423     | ORDER_NOT_READY_FOR_OPERATION   |\tOrder is locked because another operation is in progress\n"
          content:
            application/json:
              $ref: '#/paths/~1orders~1create~1v3/post/responses/400/content/application~1json'
  /orders/{yelp_order_id}/user_info/v3:
    get:
      tags:
      - Checkout API
      summary: Get User Fulfillment Info
      operationId: get_user_fulfillment_info
      description: 'Get user-provided information for delivery or fulfillment purposes.


        This may only be called after the user submitted their billing or fulfillment info on Yelp''s checkout page (i.e. Order status needs to be anything but `pending_user_submit`).


        This depends on what the Partner specified for the Order''s service type.


        For example, for Orders of `at_customer` this may be `customer_address` and `phone`.


        See FulfillmentUserInfo for more info.'
      parameters:
      - $ref: '#/paths/~1orders~1{yelp_order_id}~1update~1v3/put/parameters/0'
      responses:
        '200':
          description: Successfully retrieved user fulfillment info.
          content:
            application/json:
              examples:
                Result:
                  value:
                    fulfillment_user_info:
                      first_name: First Name
                      last_name: Last Name
                      email: email@example.com
                      phone: '1234567890'
                      availability_constraints":
                      - object: CustomerAddressConstraint
                        customer_address_str": 123 Main St., SF, 94102
                        customer_address:
                          object: Address
                          address1: 123 Main St.
                          city: San Francisco
                          postal_code: '94102'
              schema:
                type: object
                properties:
                  fulfillment_user_info:
                    type: object
                    properties:
                      first_name:
                        type: string
                      last_name:
                        type: string
                      email:
                        type: string
                      phone:
                        type: string
                      availability_constraints:
                        type: array
                        items:
                          $ref: '#/paths/~1opportunities~1{opportunity_id}~1v3/get/responses/200/content/application~1json/schema/properties/availability_constraints/items'
        '403':
          description: "This error is returned in any of the following scenarios:\n\n| Status  |\terror_code        | error_message (example)\n| ------- | ------------------- | ------------------------------\n| 403     | ORDER_STATE_INVALID |\tOrder is in an invalid state to perform this operation. (The Order must be in a state after `pending_user_submit`)\n"
          content:
            application/json:
              $ref: '#/paths/~1orders~1create~1v3/post/responses/400/content/application~1json'
components:
  securitySchemes:
    basic:
      type: http
      scheme: basic
x-provenance:
  method: searched
  source: https://docs.developer.yelp.com/reference
  harvested: '2026-11-05'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.developer.yelp.com/reference/cancel_order.md
  - https://docs.developer.yelp.com/reference/create_order.md
  - https://docs.developer.yelp.com/reference/get_opportunity.md
  - https://docs.developer.yelp.com/reference/get_order_status.md
  - https://docs.developer.yelp.com/reference/get_status_change_notifications.md
  - https://docs.developer.yelp.com/reference/get_user_fulfillment_info.md
  - https://docs.developer.yelp.com/reference/update_order.md
  - https://docs.developer.yelp.com/reference/update_order_status.md
  merge:
    pages: 8
    deduped: 17
    conflicts_kept_first: 0