openapi: 3.1.0
info:
  title: Powered by Gopuff Fulfillment API
  description: >-
    Partner-facing API powering the Powered by Gopuff Shopify Fulfillment app and the Storefronts
    Powered by Gopuff theme. The API determines whether a consumer's address falls inside a Gopuff
    micro-fulfillment center (MFC) delivery zone, exposes real-time product availability at the
    serving MFC, surfaces Gopuff carrier rates at Shopify checkout, and accepts orders that should
    be routed to Gopuff for picking, packing, and delivery in roughly 15 to 30 minutes. The
    canonical entry point is the shops resource wired into the Powered by Gopuff Shopify app embed
    block. Detailed reference documentation is published by Gopuff as "coming soon"; the surfaces
    captured here are derived from the partner Help Center and the Powered by Gopuff Shopify theme
    behavior.
  version: '1.0'
  contact:
    name: Powered by Gopuff Partner Support
    url: https://poweredby.gopuff.com/
  termsOfService: https://www.gopuff.com/go/terms-and-conditions
externalDocs:
  description: Powered by Gopuff Partner Documentation
  url: https://docs.poweredbygopuff.com/
servers:
  - url: https://fulfillment-api-eus.partners.gopuff.com/shopify/v1
    description: Production Partner API (US East)
tags:
  - name: Shops
    description: >-
      Manage the binding between a partner Shopify shop and the Powered by Gopuff partnership.
  - name: Zones
    description: >-
      Check whether a consumer address or IP location falls inside a Gopuff micro-fulfillment
      center (MFC) delivery zone.
  - name: Availability
    description: >-
      Look up real-time product availability at the Gopuff MFC servicing a given customer
      location.
  - name: Rates
    description: >-
      Return Gopuff Instant Delivery carrier rates for a Shopify checkout, alongside the
      merchant's standard shipping options.
  - name: Orders
    description: >-
      Route completed Shopify checkouts to Gopuff for picking, packing, and last-mile delivery
      from the nearest MFC.
security:
  - partnerApiKey: []
paths:
  /shops:
    get:
      operationId: getShop
      summary: Get Partner Shop Status
      description: >-
        Returns the partnership status, configured shop metadata, and serving region for the
        authenticated partner Shopify shop.
      tags:
        - Shops
      responses:
        '200':
          description: Shop record found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shop'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No shop found for the provided credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /shops/zones/check:
    post:
      operationId: checkDeliveryZone
      summary: Check Delivery Zone Eligibility
      description: >-
        Determines whether a customer location is inside a Gopuff MFC delivery zone. Either an
        address or a coarse IP location can be supplied. When the customer is in zone, the
        response includes the serving MFC identifier and the eligible product collection so the
        Powered by Gopuff Shopify theme can selectively enable instant delivery messaging.
      tags:
        - Zones
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZoneCheckRequest'
      responses:
        '200':
          description: Zone check completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneCheckResponse'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /shops/availability:
    post:
      operationId: getProductAvailability
      summary: Get Product Availability
      description: >-
        Returns real-time product availability at the Gopuff MFC servicing a given customer
        location. Products are matched via UPC mapped to the Gopuff catalog during partner
        onboarding; only items in the partner's curated instant-delivery collection are checked.
      tags:
        - Availability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailabilityRequest'
      responses:
        '200':
          description: Availability returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityResponse'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /shops/rates:
    post:
      operationId: getCarrierRates
      summary: Get Carrier Rates
      description: >-
        Returns Gopuff Instant Delivery carrier rates for a Shopify checkout. Invoked by the
        Shopify Carrier Service framework. Rates are pre-negotiated and set by the partner's
        Gopuff agreement; merchants are not allowed to add handling fees on top of the returned
        rates.
      tags:
        - Rates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierRateRequest'
      responses:
        '200':
          description: Rates returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierRateResponse'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /shops/orders:
    post:
      operationId: createOrder
      summary: Route Order to Gopuff
      description: >-
        Routes a completed Shopify checkout to the nearest Gopuff MFC for picking, packing, and
        delivery. Returns the Gopuff Order ID, which is also written back to the corresponding
        Shopify order's Additional details panel within 5 to 10 seconds.
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order accepted by Gopuff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Invalid order payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Order rejected (e.g. address out of zone, items out of stock).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /shops/orders/{order_id}:
    get:
      operationId: getOrder
      summary: Get Order
      description: >-
        Returns the current status, fulfillment lifecycle, and tracking information for a Gopuff
        order. Order status mirrors the realtime fulfillment updates Gopuff pushes to Shopify
        when the order is out for delivery and when it is delivered.
      tags:
        - Orders
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
          description: Gopuff Order ID.
      responses:
        '200':
          description: Order returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    partnerApiKey:
      type: apiKey
      in: header
      name: X-Gopuff-Partner-Key
      description: >-
        Partner API key issued by Gopuff during onboarding to the Powered by Gopuff platform.
        Keys are scoped to a single partnership/shop.
  schemas:
    Shop:
      type: object
      properties:
        shop_id:
          type: string
          description: Powered by Gopuff partner shop identifier.
        shopify_shop_domain:
          type: string
          description: The myshopify.com domain of the partner shop.
        partnership_status:
          type: string
          enum:
            - created
            - activated
            - paused
          description: Lifecycle status of the Gopuff partnership for this shop.
        region:
          type: string
          description: Serving Gopuff partner region (e.g. eus for US East).
        availability_threshold:
          type: integer
          description: Minimum number of in-stock SKUs required to consider a customer eligible.
      required:
        - shop_id
        - shopify_shop_domain
        - partnership_status
    Address:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        region:
          type: string
          description: State or province code.
        postal_code:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
      required:
        - line1
        - city
        - postal_code
        - country
    ZoneCheckRequest:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        ip_address:
          type: string
          description: Customer IP address used for coarse zone eligibility before address entry.
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
    ZoneCheckResponse:
      type: object
      properties:
        in_zone:
          type: boolean
          description: True when the location falls inside a Gopuff MFC delivery zone.
        mfc_id:
          type: string
          description: Identifier of the Gopuff micro-fulfillment center that would service the order.
        delivery_eta_minutes_min:
          type: integer
          description: Lower bound of the expected delivery window in minutes.
        delivery_eta_minutes_max:
          type: integer
          description: Upper bound of the expected delivery window in minutes.
      required:
        - in_zone
    AvailabilityRequest:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        mfc_id:
          type: string
          description: Optional MFC override if previously resolved via the zone check.
        upcs:
          type: array
          description: List of UPCs to check against the local MFC inventory.
          items:
            type: string
      required:
        - upcs
    ProductAvailability:
      type: object
      properties:
        upc:
          type: string
        available:
          type: boolean
        quantity_on_hand:
          type: integer
          description: Approximate units available at the serving MFC.
      required:
        - upc
        - available
    AvailabilityResponse:
      type: object
      properties:
        mfc_id:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProductAvailability'
      required:
        - items
    CarrierRateRequest:
      type: object
      properties:
        shipping_address:
          $ref: '#/components/schemas/Address'
        items:
          type: array
          items:
            type: object
            properties:
              upc:
                type: string
              quantity:
                type: integer
    CarrierRate:
      type: object
      properties:
        service_name:
          type: string
          description: Always "Instant Delivery - Powered by Gopuff" for Gopuff rates.
        service_code:
          type: string
        total_price:
          type: integer
          description: Rate in the smallest currency unit (e.g. cents).
        currency:
          type: string
          description: ISO 4217 currency code.
        min_delivery_minutes:
          type: integer
        max_delivery_minutes:
          type: integer
    CarrierRateResponse:
      type: object
      properties:
        rates:
          type: array
          items:
            $ref: '#/components/schemas/CarrierRate'
    CreateOrderRequest:
      type: object
      description: >-
        Mirrors the Shopify order payload submitted to Gopuff. The shipping line must carry
        "Instant Delivery - Powered by Gopuff" as the title and "Powered By Gopuff" as the
        source.
      properties:
        shopify_order_id:
          type: string
        customer:
          type: object
          properties:
            email:
              type: string
            phone:
              type: string
        shipping_address:
          $ref: '#/components/schemas/Address'
        line_items:
          type: array
          items:
            type: object
            properties:
              upc:
                type: string
              quantity:
                type: integer
              price:
                type: integer
              currency:
                type: string
        shipping_line:
          type: object
          properties:
            title:
              type: string
            source:
              type: string
      required:
        - shopify_order_id
        - shipping_address
        - line_items
    Order:
      type: object
      properties:
        gopuff_order_id:
          type: string
        shopify_order_id:
          type: string
        mfc_id:
          type: string
        status:
          type: string
          enum:
            - accepted
            - picking
            - out_for_delivery
            - delivered
            - cancelled
        tracking_url:
          type: string
          description: Realtime delivery tracking URL surfaced via SMS to the customer.
        created_at:
          type: string
          format: date-time
        delivered_at:
          type: string
          format: date-time
      required:
        - gopuff_order_id
        - status
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        request_id:
          type: string
      required:
        - code
        - message