MagicMatch by LiquiDonate

openapi: 3.1.0
info:
  title: MagicMatch by LiquiDonate
  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.
- name: Match
  description: Match items to nonprofits.
- name: Ship
  description: Purchase donation shipping labels.
- name: Donate
  description: Bulky, multi-package and pickup-scheduled donations.
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': &id001
          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': *id001
  /v1/matchAndShip/estimate:
    post:
      operationId: estimateMatchAndShip
      summary: Estimate a nonprofit match and shipping rate
      description: Returns a nonprofit match and an estimated shipping rate without creating a shipment.
        Always pass the returned match UUID into v1/matchAndShip so the same nonprofit match and rate
        are used.
      tags:
      - Match
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatchRequest'
            example: &id002
              donor:
                firstName: Test
                lastName: ABV
                email: hello@abc.com
                contactNumber: '5555555555'
              location:
                address:
                  streetAddress1: 190 Founders Prom
                  city: Getzville
                  state: NY
                  zip: '14068'
                  countryCode: US
              parcel:
                weight: 2.7
              items:
              - title: Original Bag - Ivory
                sku: ABV001
                description: ''
                quantity: 1
                categoryTypes:
                - feminine
                weightLbs: 2.5
              - title: Stroller Straps - Ivory
                sku: ABV332
                description: ''
                quantity: 1
                categoryTypes:
                - feminine
                weightLbs: 0.18
      responses:
        '200':
          description: Match and estimated rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchResponse'
              example: &id003
                match:
                  uuid: 0509dc14-dd2d-4e36-812b-52a4b2765255
                  nonprofit:
                    organizationName: Woodstock Area Counsel On Aging
                    website: https://woodstockareacounselonaging.org
                    address:
                      streetAddress1: 149 New Montgomery St.
                      streetAddress2: null
                      city: San Francisco
                      state: CA
                      zip: '94105'
                      countryCode: US
                      latitude: 38.77497
                      longitude: -122.431297
                  distanceMiles: '0'
                  items:
                  - uuid: 6e781121-14ce-4fdd-86cf-918f6472adca
                    title: MacBook Pro 13
                    sku: '500'
                    quantity: '3'
                    weight: 4
                  label:
                    trackingNumber: '9405500110368049165575'
                    carrier: USPS
                    labelURL: https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20240607/e850f7940ff8b84b3bb6eb5bd8d24fac73.png
                    rate:
                      id: ''
                      shipment_detail: null
                      value: '38.33'
                      currencyCode: USD
                  sourceLocation:
                    name: ''
                    contactNumber: ''
                    address:
                      streetAddress1: 149 New Montgomery St.
                      streetAddress2: null
                      city: San Francisco
                      state: CA
                      zip: '94105'
                      countryCode: US
                      latitude: 38.77497
                      longitude: -122.431297
        '400':
          description: Rate could not be retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                cause: error buying label
                code: retrieve_rate_error
                error: error buying label
        '401': *id001
  /v1/matchAndShip:
    post:
      operationId: matchAndShip
      summary: Match items to a nonprofit and buy the donation label
      description: Matches the supplied items to a nearby nonprofit and purchases a shipping label in
        one call. Use for standard parcel-shippable items only - furniture, mattresses, drug paraphernalia,
        items over 50 kg and items returned as Damaged are excluded; route those to v1/donate. Pass `match_uuid`
        from v1/matchAndShip/estimate to lock in the previewed match and rate.
      tags:
      - Match
      - Ship
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatchRequest'
            example: *id002
      responses:
        '200':
          description: Match created and label purchased.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchResponse'
              example: *id003
        '400':
          description: Rate could not be retrieved or the label could not be purchased.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                cause: error buying label
                code: retrieve_rate_error
                error: error buying label
        '401': *id001
        '403':
          description: The `retailer_uuid` supplied is not a child retailer of the account that owns the
            API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: retailer_not_found
                error: child retailer not found
  /v1/match:
    post:
      operationId: match
      summary: Match items to a nonprofit
      description: Returns a nonprofit match for the supplied items. Does not estimate shipping and does
        not create a shipment. If you buy your own label you must follow up with v1/match/ship so the
        nonprofit is notified of the incoming parcel and donation receipts can be generated. Same category,
        weight and damaged-return exclusions as v1/matchAndShip.
      tags:
      - Match
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatchRequest'
            example:
              donor:
                firstName: John
                lastName: Doe
                email: john.doe@liquidonate.com
                contactNumber: '123456789'
              items:
              - title: MacBook
                quantity: 1
                description: works
                sku: mackbook-1
                price: '100.00'
                categoryTypes:
                - laptops_and_computers
                conditionTagTypes:
                - new
                weightLbs: 15
              location:
                address:
                  streetAddress1: 149 New Montgomery St.
                  city: San Francisco
                  state: CA
                  zip: '94105'
                  countryCode: US
                  latitude: 38.77497
                  longitude: -122.431297
      responses:
        '200':
          description: Nonprofit match. Label fields are empty because no label was purchased.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchResponse'
        '401': *id001
  /v1/match/ship:
    post:
      operationId: attachLabelsToMatch
      summary: Attach your own shipping labels to a match
      description: Updates an existing match with labels you purchased yourself. Required after v1/match
        when you generate your own postage, so the receiving nonprofit is notified and donation receipts
        can be issued.
      tags:
      - Ship
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                match_uuid:
                  type: string
                  format: uuid
                  description: UUID of the match returned by v1/match.
                labels:
                  type: array
                  items:
                    type: object
                    properties:
                      tracking_number:
                        type: string
                      carrier:
                        type: string
                      rate:
                        type: object
                        properties:
                          amount:
                            type: number
                          currencyCode:
                            type: string
              required:
              - match_uuid
              - labels
            example:
              match_uuid: fcb6bd00-94e5-4e9d-afeb-c95515f4285a
              labels:
              - tracking_number: '12312312312'
                carrier: USPS
                rate:
                  amount: 10.2
                  currencyCode: USD
      responses:
        '200':
          description: Match updated with the supplied labels.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchResponse'
        '401': *id001
  /v1/ship:
    post:
      operationId: ship
      summary: Buy a shipping label between two fixed addresses
      description: Creates a shipment from a known source address to a known destination address. Performs
        no nonprofit matching and generates no donation receipts. Use for warehouse, fulfillment-center
        or store-originated returns where the destination is already fixed. Do not combine with v1/match
        - they are separate workflows.
      tags:
      - Ship
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                donor:
                  $ref: '#/components/schemas/Donor'
                source_location:
                  $ref: '#/components/schemas/Location'
                destination_location:
                  $ref: '#/components/schemas/Location'
                parcel:
                  type: object
                  properties:
                    weight:
                      type: number
                      format: double
                      description: Parcel weight in pounds.
              required:
              - source_location
              - destination_location
              - parcel
            example:
              donor:
                firstName: John
                lastName: Doe
                email: john.doe@liquidonate.com
                contactNumber: '123456789'
              source_location:
                address:
                  streetAddress1: 149 New Montgomery St.
                  city: San Francisco
                  state: CA
                  zip: '94105'
                  countryCode: US
                  latitude: 38.77497
                  longitude: -122.431297
              destination_location:
                address:
                  streetAddress1: 1007 sutter st
                  city: San Francisco
                  state: CA
                  zip: '94109'
                  countryCode: US
                  latitude: 37.78798780105987
                  longitude: -122.41700768673985
              parcel:
                weight: 15
      responses:
        '200':
          description: Label purchased.
          content:
            application/json:
              schema:
                type: object
                properties:
                  from:
                    $ref: '#/components/schemas/Location'
                  to:
                    $ref: '#/components/schemas/Location'
                  label:
                    $ref: '#/components/schemas/Label'
        '401': *id001
        '500':
          description: Rate could not be retrieved or the label could not be purchased.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                cause: error buying label
                code: retrieve_rate_error
                error: error buying label
  /v1/donate:
    post:
      operationId: donate
      summary: Request donation handling for bulky, multi-package or pickup items
      description: Submits an item for donation handling where standard parcel shipping does not apply
        - large or oversized goods, items needing special handling or manual review, single products shipping
        across multiple packages (supply `requestItemLabels`), and donations needing a scheduled pickup
        window (supply `pickupHours`).
      tags:
      - Donate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                item:
                  type: object
                  properties:
                    title:
                      type: string
                    quantity:
                      type: integer
                    description:
                      type: string
                    sizeType:
                      type: string
                      description: Item size band, e.g. "medium".
                      example: medium
                    fulfillmentTypes:
                      type: array
                      items:
                        type: string
                        example: pickup
                      description: How the item will be collected, e.g. "pickup".
                    recipientTypes:
                      type: array
                      items:
                        type: string
                        example: nonprofit
                      description: Eligible recipient classes, e.g. "nonprofit".
                    categoryTypes:
                      type: array
                      items:
                        $ref: '#/components/schemas/CategoryType'
                    conditionTagTypes:
                      type: array
                      items:
                        type: string
                        example: new
                    fairMarketValue:
                      $ref: '#/components/schemas/Money'
                    imageURLs:
                      type: array
                      items:
                        type: string
                        format: uri
                    location:
                      $ref: '#/components/schemas/Location'
                    unitType:
                      type: string
                      description: Unit of donation, e.g. "individual_item".
                      example: individual_item
                    weightLbs:
                      type: number
                      format: double
                    lengthInches:
                      type: number
                    heightInches:
                      type: number
                    widthInches:
                      type: number
                    requestItemLabels:
                      type: array
                      description: One entry per package when the donation ships in multiple boxes.
                      items:
                        type: object
                        properties:
                          weightInLbs:
                            type: number
                    pickupHours:
                      type: object
                      description: Pickup availability windows for scheduled collection.
                      properties:
                        timezone:
                          type: string
                          example: America/Los_Angeles
                        pickupIntervals:
                          type: array
                          items:
                            type: object
                            properties:
                              days:
                                type: array
                                items:
                                  type: string
                                  example: monday
                              startTimeLocal:
                                type: string
                                example: '10:00'
                              endTimeLocal:
                                type: string
                                example: '12:00'
                  required:
                  - title
                  - quantity
              required:
              - item
            example:
              item:
                title: Example Item
                quantity: 1
                description: This is an example description.
                sizeType: medium
                fulfillmentTypes:
                - pickup
                recipientTypes:
                - nonprofit
                categoryTypes:
                - electronics
                fairMarketValue:
                  value: 100
                  currencyCode: USD
                conditionTagTypes:
                - new
                location:
                  name: Aisya
                  contactNumber: '4125124729'
                  address:
                    streetAddress1: 123 Main St
                    streetAddress2: null
                    city: New York
                    state: NY
                    zip: '10001'
                    countryCode: US
                    latitude: 40.7128
                    longitude: -74.006
                unitType: individual_item
                weightLbs: 2.5
                lengthInches: 10
                heightInches: 5
                widthInches: 3
                pickupHours:
                  timezone: America/Los_Angeles
                  pickupIntervals:
                  - days:
                    - monday
                    - tuesday
                    startTimeLocal: '10:00'
                    endTimeLocal: '12:00'
      responses:
        '200':
          description: Donation request accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  item:
                    type: object
                    properties:
                      uuid:
                        type: string
                        format: uuid
              example:
                item:
                  uuid: efab1900-3dd3-48b6-9f1a-1c8ac58ccbec
        '400':
          description: Validation failed on the item payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: missing_item_title
                error: Item needs to have a title
        '401': *id001
components:
  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_`.
  schemas:
    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
    Location:
      type: object
      properties:
        name:
          type: string
        contactNumber:
          type: string
        contactEmail:
          type: string
        notes:
          type: string
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
      required:
      - address
    Donor:
      type: object
      description: The person donating or returning the items.
      properties:
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        email:
          type: string
          format: email
          example: john.doe@liquidonate.com
        contactNumber:
          type: string
          example: '123456789'
      required:
      - firstName
      - lastName
      - email
    Money:
      type: object
      properties:
        value:
          type: number
          example: 100
        currencyCode:
          type: string
          example: USD
    Rate:
      type: object
      properties:
        id:
          type: string
        shipment_detail:
          type: object
          nullable: true
        value:
          type: string
          description: Shipping rate as a decimal string.
          example: '38.33'
        currencyCode:
          type: string
          example: USD
    Label:
      type: object
      description: A purchased shipping label for the donation parcel.
      properties:
        trackingNumber:
          type: string
          example: '9405500110368049165575'
        carrier:
          type: string
          example: USPS
        labelURL:
          type: string
          format: uri
          description: Downloadable postage label image.
        rate:
          $ref: '#/components/schemas/Rate'
    RequestItem:
      type: object
      description: An item being donated or returned.
      properties:
        title:
          type: string
          example: Original Bag - Ivory
        sku:
          type: string
          example: ABV001
        description:
          type: string
        quantity:
          type: integer
          example: 1
        price:
          type: string
          example: '100.00'
        categoryTypes:
          type: array
          description: One or more LiquiDonate item categories. Drives nonprofit matching.
          items:
            $ref: '#/components/schemas/CategoryType'
        conditionTagTypes:
          type: array
          items:
            type: string
            example: new
          description: Condition tags for the item, e.g. "new".
        weightLbs:
          type: number
          format: double
          example: 2.5
      required:
      - title
      - quantity
    MatchItem:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        title:
          type: string
        sku:
          type: string
        quantity:
          type: string
          description: Quantity, returned as a string.
        weight:
          type: number
          format: double
    Nonprofit:
      type: object
      description: The nonprofit LiquiDonate matched the items to.
      properties:
        organizationName:
          type: string
          example: Woodstock Area Counsel On Aging
        website:
          type: string
          example: https://woodstockareacounselonaging.org
        address:
          $ref: '#/components/schemas/Address'
    Match:
      type: object
      description: A nonprofit match, optionally with a purchased shipping label.
      properties:
        uuid:
          type: string
          format: uuid
          description: Match UUID. Pass to v1/matchAndShip or v1/match/ship to keep the same match and
            rate.
        rma_id:
          type: string
          nullable: true
        nonprofit:
          $ref: '#/components/schemas/Nonprofit'
        distanceMiles:
          type: string
          description: Distance to the matched nonprofit, in miles.
          example: '7.38'
        rate:
          type: string
          description: Shipping rate as a decimal string.
          example: '36.94'
        items:
          type: array
          items:
            $ref: '#/components/schemas/MatchItem'
        label:
          $ref: '#/components/schemas/Label'
        labels:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Label'
        sourceLocation:
          $ref: '#/components/schemas/Location'
    Error:
      type: object
      description: LiquiDonate error envelope. Not RFC 9457 problem+js

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/openapi/liquidonate-magicmatch-openapi.yml