Offer codes

Every offer on the United Pet Club marketplace has an offer code: 10 characters such as K7M2Q4X9A3, assigned when the offer is created. It identifies one seller’s offer of a product, the way an FNSKU identifies a seller’s listing of an ASIN. The product itself has its own item code (the store URL key), shared by every seller of it. The two codes never collide, so one search box can take either.

A code is immutable and never reused: a withdrawn or expired offer keeps its code, and the code keeps resolving. It is not a secret either. It is printed on packages and shown on the product page.

Resolve a code

GET /api/marketplace/v1/codes/{code}

Anonymous: no token is needed. {code} is the 10 characters, in any case; the internal prefixed form UPC-OF-K7M2Q4X9A3 is accepted too. Responses use the platform envelope; read the payload from data.

{
  "data": {
    "code": "K7M2Q4X9A3",
    "offerId": "0f7a4c1e-3333-7000-8000-000000000003",
    "storefrontId": "0f7a4c1e-1111-7000-8000-000000000001",
    "publicCode": "UPC-OF-K7M2Q4X9A3",
    "isLiveFlag": true,
    "storefrontHandle": "unitedpetcommerce",
    "slug": "reflective-dog-leash-blue",
    "catalogItemId": "0f7a4c1e-5555-7000-8000-000000000005",
    "catalogItemCode": "QVWLQEA432"
  }
}

Field	Meaning
code	The code, upper case, without a prefix. Show this one.
offerId	The offer.
storefrontId, storefrontHandle	The seller’s storefront. storefrontId is all zeros when the offer no longer exists.
publicCode	The internal prefixed form. Keep it for logs; don’t show it to people.
isLiveFlag	true while the offer is active and its storefront is active. false for a withdrawn or expired offer or an inactive storefront: the code still names it.
slug	The offer’s slug in its primary locale, when it has a name.
catalogItemId, catalogItemCode	The product the offer sells, and its item code. Both null for offers that sell no catalog item (bundles, pledges).

An unknown or malformed code (anything but 6–20 letters and digits) answers 404. Minted codes use only the letters A–Z and the digits 2–7, so a code with a 0, 1, 8 or 9 in it was misread.

Link to the product

With catalogItemCode, https://www.unitedpetclub.com/store/{catalogItemCode} opens the product page and redirects to its canonical URL. You can also send a shopper to the store search with the offer code itself: https://www.unitedpetclub.com/store/search?q=K7M2Q4X9A3 opens the product that offer sells. Offer codes never appear in store URLs.

Offer reads carry the code

The public offer reads return the code as offerCode, right after id:

• GET /api/marketplace/v1/offers/{id}
• GET /api/marketplace/v1/offers/by-storefront/{storefrontId}
• the offers listed on a product (GET /api/marketplace/v1/offers/by-catalog-item/{catalogItemId})

{ "id": "0f7a4c1e-3333-7000-8000-000000000003", "offerCode": "K7M2Q4X9A3", "storefrontId": "…", "statusCode": "ACTIVE" }

Print it on your packages

If you pack orders for a United Pet Club seller, print the offer code on each parcel. Support and the seller use it to trace a parcel to the exact offer, even after the offer was withdrawn. Labels bought from the seller’s Dashboard do this already: when the seller leaves the package reference blank, the label’s reference is the order’s offer codes, as many whole codes as the carrier’s reference field holds.