Instacart

instacart Replacements API

Endpoints for managing item replacements suggested by shoppers during order fulfillment.

Documentation GitHub OpenAPI

Operations 1

PUT /v2/post_checkout/orders/{order_id}/items/{order_item_id}/replacement Approve or reject an item replacement #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/instacart-replacements-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Instacart Connect Post-Checkout Replacements API
  description: The Instacart Connect Post-Checkout API allows retailers to provide their customers with real-time order tracking and shopper interaction after an order has been placed. Retailers can use this API to build custom order status pages that display order details, live tracking information, and shopper communication. Customers can see updates while their order is being shopped and delivered, approve or decline item replacements suggested by shoppers, and communicate directly with shoppers via chat about replacements and additions.
  version: '2.0'
  contact:
    name: Instacart Connect Support
    url: https://docs.instacart.com/connect/post-checkout/
  termsOfService: https://www.instacart.com/terms
servers:
- url: https://connect.instacart.com
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Replacements
  description: Endpoints for managing item replacements suggested by shoppers during order fulfillment.
paths:
  /v2/post_checkout/orders/{order_id}/items/{order_item_id}/replacement:
    put:
      operationId: updateItemReplacement
      summary: Approve or reject an item replacement
      description: Approves or rejects a replacement suggested by the shopper for a specific order item. If the customer approves the replacement, specify the status as APPROVED. If the customer rejects the replacement, specify the status as REJECTED. Items with a rejected replacement are automatically refunded.
      tags:
      - Replacements
      parameters:
      - $ref: '#/components/parameters/orderId'
      - $ref: '#/components/parameters/orderItemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplacementDecisionRequest'
      responses:
        '200':
          description: Replacement decision applied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplacementResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ReplacementDecisionRequest:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - APPROVED
          - REJECTED
          description: The customer's decision on the replacement. APPROVED accepts the replacement. REJECTED declines the replacement and triggers an automatic refund.
    ReplacementResponse:
      type: object
      properties:
        id:
          type: string
          description: The order item identifier.
        replacement_status:
          type: string
          enum:
          - APPROVED
          - REJECTED
          description: The updated replacement status.
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
        status:
          type: integer
          description: The HTTP status code.
  parameters:
    orderItemId:
      name: order_item_id
      in: path
      required: true
      description: The unique identifier for a specific item within the order.
      schema:
        type: string
    orderId:
      name: order_id
      in: path
      required: true
      description: The unique identifier for the order.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token obtained from the access token endpoint. A user access token is required for post-checkout operations.
externalDocs:
  description: Instacart Connect Post-Checkout API Documentation
  url: https://docs.instacart.com/connect/post-checkout/