Skip to content

Find an offer

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

GET/preorders/offer_lookup

Costs 1 rate-limit point · Rate limits

Resolve one preorder offer from an exact id or a fuzzy name match. Returns the full offer (same shape as GET /preorders/offers/:id) on a unique match. If name matches more than one offer, returns {ambiguous: true, candidates: [...]} instead of guessing -- re-call with the chosen id. Omit both id and name for the most recently created offer.

name is compared without regard to case against both the offer's name and its internal_name. An exact match wins over partial ones, so name=Preorder returns the offer called exactly that even when other offers contain the word. Otherwise any offer whose name contains the text, or is contained in it, matches. Deleted offers are never returned. An offer id passed as name also works. No match returns 404 not_found; an empty name returns 422 validation_failed.

Also searched asfind offerresolve offerlook up offer by namewhich offerthe offer

Query parameters

  • idstring

    Exact offer ID to return. Wins over name when both are sent.

  • namestring

    Text matched against each offer's name and internal name, exact first, then partial. Omit both id and name for the most recently created offer.

Returns

  • idstring
    Example: string
  • shopify_selling_plan_group_idstring
    Example: string
  • namestring
    Example: string
  • internal_namestring
    Example: string
  • widgetobject
    Show 3 child attributesHide child attributes
    • buttonobject
      Show 4 child attributesHide child attributes
      • button_textstring
        Example: string
      • custom_colors_enabledboolean
        Example: true
      • text_colorstring
        Example: string
      • background_colorstring
        Example: string
    • disclaimerobject
      Show 5 child attributesHide child attributes
      • show_disclaimerboolean
        Example: true
      • disclaimer_textstring
        Example: string
      • text_colorstring
        Example: string
      • background_colorstring
        Example: string
      • border_radiusinteger
        Example: 1
    • badgeobject
      Show 4 child attributesHide child attributes
      • show_badgeboolean
        Example: true
      • badge_textstring
        Example: string
      • text_colorstring
        Example: string
      • background_colorstring
        Example: string
  • inventoryobject
    Show 2 child attributesHide child attributes
    • stock_conditionstring
      Example: string
    • reservestring
      Example: string
  • productsobject
    Show 7 child attributesHide child attributes
    • selectionstring
      Example: string
    • shopify_collection_idnull
    • tagsarray of anys
    • eligible_inventory_policystring
      Example: string
    • excluded_shopify_variant_idsarray of anys
    • exclusion_tagnull
    • variant_countinteger
      Example: 1
  • shippingobject
    Show 6 child attributesHide child attributes
    • timelineobject
      Show 4 child attributesHide child attributes
      • scopestring
        Example: string
      • show_shipping_textboolean
        Example: true
      • shipping_textstring
        Example: string
      • variant_shipping_textstring
        Example: string
    • delivery_timingstring
      Example: string
    • ships_atnull
    • days_after_checkoutnull
    • fulfillmentobject
      Show 3 child attributesHide child attributes
      • handlingstring
        Example: string
      • hold_reasonstring
        Example: string
      • separate_ordersobject
        Show 8 child attributesHide child attributes
        • groupingstring
          Example: string
        • number_formatstring
          Example: string
        • suffixstring
          Example: string
        • hold_fulfillmentsboolean
          Example: true
        • tagstring
          Example: string
        • transaction_gatewaystring
          Example: string
        • original_order_hold_tagnull
        • original_order_split_tagnull
    • on_holdobject
      Show 3 child attributesHide child attributes
      • release_schedulestring
        Example: string
      • release_atnull
      • require_paymentboolean
        Example: true
  • paymentsobject
    Show 7 child attributesHide child attributes
    • options_offeredstring
      Example: string
    • default_optionstring
      Example: string
    • fullobject
      Show 7 child attributesHide child attributes
      • selling_plan_idnull
      • checkout_chargeobject
        Show 2 child attributesHide child attributes
        • charge_typestring
          Example: string
        • charge_amountinteger
          Example: 1
      • remaining_balanceobject
        Show 3 child attributesHide child attributes
        • charge_triggerstring
          Example: string
        • charge_exact_timenull
        • days_after_checkoutnull
      • price_adjustmentobject
        Show 2 child attributesHide child attributes
        • adjustment_typenull
        • adjustment_amountnull
      • option_titlestring
        Example: string
      • option_descriptionstring
        Example: string
      • discount_textstring
        Example: string
    • collection_schedulestring
      Example: string
    • show_payment_widgetboolean
      Example: true
    • show_discounted_pricenull
    • currency_codenull
  • availabilityobject
    Show 5 child attributesHide child attributes
    • schedulestring
      Example: string
    • starts_atnull
    • ends_atnull
    • current_statusstring
      Example: string
    • time_zonestring
      Example: string
  • limitsobject
    Show 9 child attributesHide child attributes
    • default_per_variantnull
    • display_stylestring
      Example: string
    • limit_textstring
      Example: string
    • show_iconsboolean
      Example: true
    • progress_barobject
      Show 7 child attributesHide child attributes
      • progress_textstring
        Example: string
      • fill_colorstring
        Example: string
      • background_colorstring
        Example: string
      • box_background_colornull
      • text_colorstring
        Example: string
      • border_radiusinteger
        Example: 1
      • show_percentageboolean
        Example: true
    • order_tagsarray of strings
    • termsobject
      Show 5 child attributesHide child attributes
      • require_acceptanceboolean
        Example: true
      • terms_textstring
        Example: string
      • disable_button_until_acceptedboolean
        Example: true
      • record_acceptanceboolean
        Example: true
      • acceptance_labelstring
        Example: string
    • cartobject
      Show 2 child attributesHide child attributes
      • allowed_itemsstring
        Example: string
      • error_messagestring
        Example: string
    • order_quantityobject
      Show 2 child attributesHide child attributes
      • minimumnull
      • maximumnull
  • countdownobject
    Show 12 child attributesHide child attributes
    • show_whenstring
      Example: string
    • date_sourcestring
      Example: string
    • starts_atnull
    • ends_atnull
    • starts_textnull
    • ends_textnull
    • labelsobject
      Show 4 child attributesHide child attributes
      • daysstring
        Example: string
      • hoursstring
        Example: string
      • minutesstring
        Example: string
      • secondsstring
        Example: string
    • text_colorstring
      Example: string
    • background_colorstring
      Example: string
    • border_radiusinteger
      Example: 1
    • unitsarray of strings
    • currentobject
      Show 5 child attributesHide child attributes
      • visible_phasestring
        Example: string
      • target_atnull
      • heading_textnull
      • starts_atnull
      • ends_atnull
  • marketsobject
    Show 2 child attributesHide child attributes
    • scopestring
      Example: string
    • shopify_market_idsarray of anys
  • advancedobject
    Show 2 child attributesHide child attributes
    • checkout_methodstring
      Example: string
    • cart_attributesobject
      Show 3 child attributesHide child attributes
      • show_paymentboolean
        Example: true
      • show_shippingboolean
        Example: true
      • custom_textnull
  • integrationsobject
    Show 2 child attributesHide child attributes
    • posobject
      Show 2 child attributesHide child attributes
      • enable_posboolean
        Example: true
      • inventory_checkstring
        Example: string
    • b2bobject
      Show 1 child attributeHide child attributes
      • enable_b2bboolean
        Example: true
  • batchesobject
    Show 6 child attributesHide child attributes
    • release_strategystring
      Example: string
    • advance_schedulestring
      Example: string
    • label_formatstring
      Example: string
    • status_textobject
      Show 3 child attributesHide child attributes
      • paststring
        Example: string
      • livestring
        Example: string
      • upcomingstring
        Example: string
    • widgetobject
      Show 4 child attributesHide child attributes
      • stylestring
        Example: string
      • progressstring
        Example: string
      • show_other_ship_datesboolean
        Example: true
      • show_namesboolean
        Example: true
    • itemsarray of anys
  • translationsobject
  • line_item_revenuestring
    Example: string
  • order_revenuestring
    Example: string
  • created_atstring
    Example: 2026-01-15T09:30:00Z
  • updated_atstring
    Example: 2026-01-15T09:30:00Z
  • ambiguousboolean
    Example: true
  • querystring
    Example: string
  • candidatesarray of objects
    Show 8 child attributesHide child attributes
    • idstring
      Example: string
    • namestring
      Example: string
    • internal_namestring
      Example: string
    • current_statusstring
      Example: string
    • line_item_revenuestring
      Example: string
    • order_revenuestring
      Example: string
    • created_atstring
      Example: 2026-01-15T09:30:00Z
    • updated_atstring
      Example: 2026-01-15T09:30:00Z

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

422
validation_failed

The action refused the request for a reason that is not a single bad field.

Any request can also fail with auth_invalid (401) or rate_limited (429).

Every error has the same shape: see Errors and the list of error codes.

GET/preorders/offer_lookup
curl "https://app.stoqapp.com/api/v2/external/preorders/offer_lookup" \
  -H "X-Auth-Token: $STOQ_API_KEY"
Response
{
  "id": "string",
  "shopify_selling_plan_group_id": "string",
  "name": "string",
  "internal_name": "string",
  "widget": {
    "button": {
      "button_text": "string",
      "custom_colors_enabled": true,
      "text_color": "string",
      "background_color": "string"
    },
    "disclaimer": {
      "show_disclaimer": true,
      "disclaimer_text": "string",
      "text_color": "string",
      "background_color": "string",
      "border_radius": 1
    },
    "badge": {
      "show_badge": true,
      "badge_text": "string",
      "text_color": "string",
      "background_color": "string"
    }
  },
  "inventory": {
    "stock_condition": "string",
    "reserve": "string"
  },
  "products": {
    "selection": "string",
    "shopify_collection_id": null,
    "tags": [
      null
    ],
    "eligible_inventory_policy": "string",
    "excluded_shopify_variant_ids": [
      null
    ],
    "exclusion_tag": null,
    "variant_count": 1
  },
  "shipping": {
    "timeline": {
      "scope": "string",
      "show_shipping_text": true,
      "shipping_text": "string",
      "variant_shipping_text": "string"
    },
    "delivery_timing": "string",
    "ships_at": null,
    "days_after_checkout": null,
    "fulfillment": {
      "handling": "string",
      "hold_reason": "string",
      "separate_orders": {
        "grouping": "string",
        "number_format": "string",
        "suffix": "string",
        "hold_fulfillments": true,
        "tag": "string",
        "transaction_gateway": "string",
        "original_order_hold_tag": null,
        "original_order_split_tag": null
      }
    },
    "on_hold": {
      "release_schedule": "string",
      "release_at": null,
      "require_payment": true
    }
  },
  "payments": {
    "options_offered": "string",
    "default_option": "string",
    "full": {
      "selling_plan_id": null,
      "checkout_charge": {
        "charge_type": "string",
        "charge_amount": 1
      },
      "remaining_balance": {
        "charge_trigger": "string",
        "charge_exact_time": null,
        "days_after_checkout": null
      },
      "price_adjustment": {
        "adjustment_type": null,
        "adjustment_amount": null
      },
      "option_title": "string",
      "option_description": "string",
      "discount_text": "string"
    },
    "collection_schedule": "string",
    "show_payment_widget": true,
    "show_discounted_price": null,
    "currency_code": null
  },
  "availability": {
    "schedule": "string",
    "starts_at": null,
    "ends_at": null,
    "current_status": "string",
    "time_zone": "string"
  },
  "limits": {
    "default_per_variant": null,
    "display_style": "string",
    "limit_text": "string",
    "show_icons": true,
    "progress_bar": {
      "progress_text": "string",
      "fill_color": "string",
      "background_color": "string",
      "box_background_color": null,
      "text_color": "string",
      "border_radius": 1,
      "show_percentage": true
    },
    "order_tags": [
      "string"
    ],
    "terms": {
      "require_acceptance": true,
      "terms_text": "string",
      "disable_button_until_accepted": true,
      "record_acceptance": true,
      "acceptance_label": "string"
    },
    "cart": {
      "allowed_items": "string",
      "error_message": "string"
    },
    "order_quantity": {
      "minimum": null,
      "maximum": null
    }
  },
  "countdown": {
    "show_when": "string",
    "date_source": "string",
    "starts_at": null,
    "ends_at": null,
    "starts_text": null,
    "ends_text": null,
    "labels": {
      "days": "string",
      "hours": "string",
      "minutes": "string",
      "seconds": "string"
    },
    "text_color": "string",
    "background_color": "string",
    "border_radius": 1,
    "units": [
      "string"
    ],
    "current": {
      "visible_phase": "string",
      "target_at": null,
      "heading_text": null,
      "starts_at": null,
      "ends_at": null
    }
  },
  "markets": {
    "scope": "string",
    "shopify_market_ids": [
      null
    ]
  },
  "advanced": {
    "checkout_method": "string",
    "cart_attributes": {
      "show_payment": true,
      "show_shipping": true,
      "custom_text": null
    }
  },
  "integrations": {
    "pos": {
      "enable_pos": true,
      "inventory_check": "string"
    },
    "b2b": {
      "enable_b2b": true
    }
  },
  "batches": {
    "release_strategy": "string",
    "advance_schedule": "string",
    "label_format": "string",
    "status_text": {
      "past": "string",
      "live": "string",
      "upcoming": "string"
    },
    "widget": {
      "style": "string",
      "progress": "string",
      "show_other_ship_dates": true,
      "show_names": true
    },
    "items": [
      null
    ]
  },
  "translations": {},
  "line_item_revenue": "string",
  "order_revenue": "string",
  "created_at": "2026-01-15T09:30:00Z",
  "updated_at": "2026-01-15T09:30:00Z",
  "ambiguous": true,
  "query": "string",
  "candidates": [
    {
      "id": "string",
      "name": "string",
      "internal_name": "string",
      "current_status": "string",
      "line_item_revenue": "string",
      "order_revenue": "string",
      "created_at": "2026-01-15T09:30:00Z",
      "updated_at": "2026-01-15T09:30:00Z"
    }
  ]
}