LiquiDonate Retailer API

openapi: 3.1.0
info:
  title: MagicMatch by LiquiDonate Donate Retailer API
  version: 1.0.0
  summary: 'Donation-as-a-Service: match returned or excess retail items to nearby nonprofits and buy the donation shipping label.'
  description: 'MagicMatch by LiquiDonate lets retailers, returns platforms, 3PLs, warehouse systems and reverse-logistics providers send parcel and item details to LiquiDonate and receive a nonprofit match plus a donation shipping label. The matching engine picks a nearby nonprofit that accepts the item categories supplied, and LiquiDonate purchases postage so the item ships directly from the customer or warehouse to that nonprofit, generating a donation receipt instead of a landfill-bound return.


    **Choosing an endpoint**


    - `v1/matchAndShip/estimate` - preview the nonprofit match and shipping rate without creating a shipment.

    - `v1/matchAndShip` - match and buy the label in one call. Pass the `match_uuid` from `/estimate` to keep the same match and rate.

    - `v1/match` - match only, no rate and no shipment. Follow with `v1/match/ship` if you buy your own label.

    - `v1/match/ship` - attach your own label(s) to an existing match so the nonprofit is notified and receipts are generated.

    - `v1/ship` - buy a label between two fixed addresses. No nonprofit matching and no donation receipts.

    - `v1/donate` - bulky, oversized, multi-package or pickup-scheduled donations that fall outside standard parcel shipping.


    **Exclusions for matching endpoints** (per the published docs): furniture, mattresses and drug paraphernalia are excluded; items over 50 kg are excluded; items with a "Damaged" return reason are excluded. Use `v1/donate` for furniture, mattresses and heavy items.


    This description is an API Evangelist reconstruction of the published Postman documentation at https://docs-magicmatch.liquidonate.com - LiquiDonate does not publish an OpenAPI definition.'
  contact:
    name: LiquiDonate
    url: https://docs-magicmatch.liquidonate.com
    email: sales@liquidonate.com
  termsOfService: https://www.liquidonate.com/terms-of-service
  x-source: https://docs-magicmatch.liquidonate.com
  x-source-collection: https://documenter.getpostman.com/view/21205794/2sA3QteBZu
  x-generated-by: api-evangelist enrichment pipeline
  x-generated: '2026-07-19'
servers:
- url: https://api.liquidonate.com
  description: 'Production. Verified live: unauthenticated requests return 401 {"error":"invalid api key or secret"}.'
security:
- liquidonateKey: []
  liquidonateSecret: []
tags:
- name: Retailer
  description: Retailer account setup and lookup.
paths:
  /v1/setupRetailer:
    post:
      operationId: setupRetailer
      summary: Set up a retailer account
      description: Registers retailer details and returns the API key and secret used to authenticate every other endpoint. Also used to create child retailers under a parent account.
      tags:
      - Retailer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                retailer:
                  type: object
                  properties:
                    name:
                      type: string
                    businessPhoneNumber:
                      type: string
                    businessAddress:
                      $ref: '#/components/schemas/Address'
                    shopifyShopID:
                      type: string
                    website:
                      type: string
                    description:
                      type: string
                  required:
                  - name
                user:
                  type: object
                  properties:
                    firstName:
                      type: string
                    lastName:
                      type: string
                    email:
                      type: string
                      format: email
                    phone:
                      type: string
                  required:
                  - firstName
                  - lastName
                  - email
              required:
              - retailer
              - user
            example:
              retailer:
                name: LiquiDonate - Test Child
                businessPhoneNumber: '123456789'
                businessAddress:
                  streetAddress1: 149 New Montgomery Street
                  streetAddress2: Floor 4
                  city: San Francisco
                  state: CA
                  zip: '94105'
                  countryCode: US
                shopifyShopID: '1234567890'
                website: https://www.liquidonate.com
                description: https://www.liquidonate.com
              user:
                firstName: Aisya
                lastName: Aziz
                email: aisya@liquidonate.com
                phone: '1234567890'
      responses:
        '200':
          description: Retailer created. Store the returned key and secret securely - they are shown once.
          content:
            application/json:
              schema:
                type: object
                properties:
                  retailer:
                    type: object
                    properties:
                      uuid:
                        type: string
                        format: uuid
                      name:
                        type: string
                  user:
                    type: object
                    properties:
                      uuid:
                        type: string
                        format: uuid
                  apiKey:
                    type: object
                    properties:
                      key:
                        type: string
                        description: API key, prefixed `ld_`.
                      secret:
                        type: string
                        description: API secret, prefixed `ld_sk_`.
        '401':
          description: Missing or invalid API key/secret. Verified live against https://api.liquidonate.com.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: invalid api key or secret
  /v1/getRetailer:
    post:
      operationId: getRetailer
      summary: Retrieve the retailer account
      description: Returns the retailer profile associated with the API key and secret in the request headers.
      tags:
      - Retailer
      responses:
        '200':
          description: Retailer profile.
          content:
            application/json:
              schema:
                type: object
                properties:
                  retailer:
                    type: object
                    properties:
                      uuid:
                        type: string
                        format: uuid
                      name:
                        type: string
                      description:
                        type: string
                      phone_number:
                        type: string
                      website:
                        type: string
              example:
                retailer:
                  description: https://www.liquidonate.com
                  name: LiquiDonate
                  phone_number: '123456789'
                  uuid: bdf80b3a-1dad-4d2f-b5fd-94a6b7f733e2
                  website: https://www.liquidonate.com
        '401':
          description: Missing or invalid API key/secret. Verified live against https://api.liquidonate.com.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: invalid api key or secret
components:
  schemas:
    Error:
      type: object
      description: LiquiDonate error envelope. Not RFC 9457 problem+json.
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: retrieve_rate_error
        error:
          type: string
          description: Human-readable error message.
          example: error buying label
        cause:
          type: string
          description: Underlying cause, when available.
    Address:
      type: object
      description: A US postal address. Latitude/longitude are optional; LiquiDonate geocodes when omitted.
      properties:
        streetAddress1:
          type: string
          example: 149 New Montgomery St.
        streetAddress2:
          type: string
          nullable: true
          example: Floor 4
        city:
          type: string
          example: San Francisco
        state:
          type: string
          description: Two-letter state code.
          example: CA
        zip:
          type: string
          example: '94105'
        countryCode:
          type: string
          example: US
        latitude:
          type: number
          format: double
          nullable: true
          example: 38.77497
        longitude:
          type: number
          format: double
          nullable: true
          example: -122.431297
      required:
      - streetAddress1
      - city
      - state
      - zip
      - countryCode
  securitySchemes:
    liquidonateKey:
      type: apiKey
      in: header
      name: X-LiquiDonate-Key
      description: Retailer API key issued by v1/setupRetailer. Prefixed `ld_`.
    liquidonateSecret:
      type: apiKey
      in: header
      name: X-LiquiDonate-Secret
      description: Retailer API secret issued by v1/setupRetailer. Prefixed `ld_sk_`.