WCP Migration — API Partner Guide

US Item ID Rollout: What Changes for You

---

Overview

Sam's Club Sponsored Products is introducing US Item IDs as the canonical identifier for items in ad campaigns. This migration changes the format of item identifiers returned by and sent to several API endpoints.

This document covers only what you, as an API partner, need to know: what changes, when, and how to adapt your integration.

Migration is advertiser-scoped. Your integration is only affected once your advertiser account is enabled for US Item IDs. However, all accounts will be forcefully migrated on July 31, 2026 — action is required before that date.

---

1. Item ID Format Change

	Before (Legacy)	After (US Item ID)
Format	Prefixed catalog string	Numeric string
Example	prod23602570	23602570
Character set	Alphanumeric with prod prefix	Digits only
Length	Variable	10 digits (zero-padded if needed)

You do not need to convert IDs yourself. The API accepts and returns the correct format automatically based on your account's migration status.

---

2. Which Accounts Are Affected

Account Status	Item ID format in requests	Item ID format in responses
Not yet migrated	Legacy (prod23602570) — no change needed	Legacy (prod23602570)
Migrated	US Item ID (23602570)	US Item ID (23602570)

Migration is enabled per advertiser account. Your account will not change behavior until it is explicitly enabled by Sam's Club. Contact your partner integration team to confirm your account's status.

⚠️ Forced cutover: July 31, 2026. All advertiser accounts will be migrated to US Item IDs on this date regardless of opt-in status. Legacy prod-prefixed item IDs will stop working after this date. Ensure your integration is updated and tested before July 31, 2026.

---

3. Affected Endpoints

Only item-related endpoints change behavior. All other endpoints (campaigns, ad groups, keywords, bid multipliers, reports, SBA profiles) are unchanged.

Endpoint	Method	Change
/api/v1/itemSearch	POST	Returns items in US Item ID format for migrated advertisers
/api/v1/adItems	POST	Accepts & returns US Item IDs for migrated advertisers
/api/v1/adItems	GET	Returns items with US Item IDs for migrated advertisers
/api/v1/adItems	PUT	Accepts US Item IDs in update payloads

All other endpoints remain unchanged and require no updates to your integration.

---

4. Endpoint Behavior Details

4.1 Item Search — POST /api/v1/itemSearch

Search for items to add to your ad group. Use either searchText or searchItemIds — not both.

Request — by searchText (unchanged):

{
  "advertiserId": 12345,
  "searchText": "organic chicken"
}

Request — by searchItemIds (unchanged):

{
  "advertiserId": 12345,
  "searchItemIds": ["prod23602570"]
}

Response — non-migrated advertiser:

[
  {
    "itemId": "prod23602570",
    "itemName": "Organic Chicken 3lb",
    "suggestedBid": 0.40,
    "itemImageUrl": "https://scene7.samsclub.com/is/image/...",
    "itemPageUrl": "https://www.samsclub.com/p/...",
    "variantItems": [
      {
        "variantItemId": "prod23602570",
        "variantItemName": "Organic Chicken 3lb",
        "variantImageUrl": "https://scene7.samsclub.com/is/image/..."
      }
    ]
  }
]

Response — migrated advertiser:

[
  {
    "itemId": "23602570",
    "itemName": "Organic Chicken 3lb",
    "suggestedBid": 0.40,
    "itemImageUrl": "https://scene7.samsclub.com/is/image/...",
    "itemPageUrl": "https://www.samsclub.com/p/...",
    "variantItems": [
      {
        "variantItemId": "23602570",
        "variantItemName": "Organic Chicken 3lb",
        "variantImageUrl": "https://scene7.samsclub.com/is/image/..."
      }
    ]
  }
]

Use the itemId returned here directly when adding items to your ad group — do not transform or construct it. The variantItemId values in variantItems also follow the same format.

---

4.2 Add Items — POST /api/v1/adItems

Add one or more items to an ad group. Each item is sent as a flat object in the request array.

Request (unchanged structure):

[
  {
    "campaignId": 1234,
    "adGroupId": 9999,
    "itemId": "23602570",
    "bid": 1.25,
    "status": "enabled"
  }
]

Response — non-migrated advertiser:

[
  {
    "code": "success",
    "details": "",
    "adItemId": 600001
  }
]

The itemId stored internally maps to the legacy format (prod23602570) for non-migrated accounts.

Response — migrated advertiser:

[
  {
    "code": "success",
    "details": "",
    "adItemId": 600002
  }
]

The itemId stored internally maps to the US Item ID format (23602570) for migrated accounts.

The adItemId in the response is the row ID you will use for reference. Use itemId from a subsequent GET to retrieve the item's format-correct identifier.

---

4.3 Get Items — GET /api/v1/adItems

Retrieve items for an ad group.

Request parameters (unchanged):

GET /api/v1/adItems?campaignId=1234

The response itemId field reflects the format appropriate for your advertiser's migration status — no request changes needed.

---

4.4 Update Item Bid — PUT /api/v1/adItems

Update bid or status for an ad item.

Request (unchanged structure):

[
  {
    "campaignId": 1234,
    "adGroupId": 9999,
    "itemId": "23602570",
    "bid": 1.50,
    "status": "enabled"
  }
]

Use campaignId, adGroupId, and itemId exactly as returned by the GET response. Valid status values: enabled, disabled, deleted.

---

5. Error Responses

5.1 HTTP-level errors

All HTTP-level errors use a single "error" field with a plain English message:

{ "error": "<message>" }

HTTP	Situation	Example message
400	Missing required field	"Field [adGroupId] not found in request"
400	Malformed request body	"Invalid request parameter(s)"
403	Advertiser does not own the ad group	"You don't have permission to edit this ad group."
404	Ad group not found	"AdGroup not found."
404	Ad group item not found	"AdGroupItem not found."
500	Unexpected server error	"There was an error processing the request"

5.2 Per-item errors in POST /adItems and PUT /adItems

Item add and update operations always return HTTP 200, even when individual items fail. Check the code field per item:

[
  {
    "adItemId": 556,
    "code": "success",
    "details": ""
  },
  {
    "adItemId": 0,
    "code": "failure",
    "details": "Item Id not found."
  }
]

details value	Meaning
"Item Id not found."	Item does not exist in the catalog
"ITEMID_NOT_FOUND, Input id: <id>"	Item ID format does not match your account's migration status — see table below
"Item not found, Input id: <id>"	Item exists but could not be retrieved
"Cannot upload unpublished item, Input id: <id>"	Item is not published
"Cannot upload item. item or base item not owned by you, Input id: <id>"	Item ownership mismatch
"Item is missing bid value, Input id: <id>"	bid not provided
"Bid should be higher than : <floor>"	CPC below floor

When will I see "ITEMID_NOT_FOUND, Input id: ..."?

This error occurs when the item ID format you pass does not match what your account expects:

Account status	ID you passed	Result
Migrated	US Item ID (23602570)	✅ Success
Migrated	Legacy ID (prod23602570)	❌ code: "failure", details: "ITEMID_NOT_FOUND, Input id: prod23602570"
Not migrated	Legacy ID (prod23602570)	✅ Success
Not migrated	US Item ID (23602570)	❌ code: "failure", details: "ITEMID_NOT_FOUND, Input id: 23602570"

Recommendation: Always use item IDs sourced from /api/v1/itemSearch or a prior /adItems GET — they are always in the correct format for your account. Never construct or transform item IDs manually.

---

6. End-to-End Workflows

6.1 Launching a New Campaign

flowchart TD
    classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a5f,rx:4
    classDef decision fill:#fef9c3,stroke:#ca8a04,color:#713f12
    classDef ok fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef fail fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
    classDef term fill:#f3e8ff,stroke:#7c3aed,color:#3b0764

    START([Partner starts integration]) --> S1

    subgraph SETUP["Campaign Setup"]
        S1["POST /api/v1/campaigns\nname · budget · targetingType"]:::api
        S1 -->|returns campaignId| S2
        S2["POST /api/v1/adGroups\nname · campaignId · status"]:::api
        S2 -->|returns adGroupId| S3
    end

    subgraph ITEMS["Item Discovery and Addition"]
        S3["POST /api/v1/itemSearch\nadvertiserId · searchText or searchItemIds"]:::api
        S3 --> MIG{Account migrated?}:::decision
        MIG -->|"Yes — itemId is numeric\ne.g. 23602570"| S3A
        MIG -->|"No — itemId is prefixed\ne.g. prod23602570"| S3A
        S3A["POST /api/v1/adItems\ncampaignId · adGroupId\nitemId · bid · status"]:::api
        S3A --> ITEMCHK{Per-item code?}:::decision
        ITEMCHK -->|"code: failure\ncheck details field"| ITEMFIX["Fix item ID or bid\nand retry"]:::fail
        ITEMFIX --> S3A
        ITEMCHK -->|"code: success\nfor all items"| S4
    end

    subgraph KEYWORDS["Keywords"]
        S4["POST /api/v1/keywords\nadGroupId · keywords · matchType · bid"]:::api
        S4 -->|returns keywordIds| S5
    end

    subgraph REVIEW["Review and Launch"]
        S5["POST /api/v1/review\nadGroupId"]:::api
        S5 -->|reviewId · status submitted| POLL
        POLL["GET /api/v1/review\npoll for outcome"]:::api
        POLL --> RVCHK{Review status}:::decision
        RVCHK -->|"rejected — update items\nor keywords and resubmit"| CANCEL["PUT /api/v1/review\ncancel pending review"]:::fail
        CANCEL --> S4
        RVCHK -->|"approved\ncampaign auto-schedules"| LIVE
        LIVE(["Campaign live"]):::ok
    end

    LIVE --> RPT["POST /api/v1/snapshot/report\nreportType: adItem · adGroup · platform · ..."]:::api
    RPT --> DONE(["Reports available"]):::term

Step 1: Create a Campaign

Endpoint: POST /api/v1/campaigns
Response: campaignId
Conditions / Recommendations:

• Use targetingType: manual for keyword-targeted campaigns
• Set both budget (total) and dailyBudget to control spend

Step 2: Create an Ad Group

Endpoint: POST /api/v1/adGroups
Response: adGroupId
Conditions / Recommendations:

• Currently, only one ad group is permitted per campaign
• Use the campaignId returned in Step 1

Step 3: Search for Items to Advertise

Endpoint: POST /api/v1/itemSearch
Response: list of items with itemId, name, and price
Conditions / Recommendations:

• Use the itemId returned here directly in Step 4 — do not transform or construct it
• For migrated advertisers, item IDs are returned in US Item ID format (numeric, e.g. 23602570)
• For non-migrated advertisers, item IDs are returned in legacy format (e.g. prod23602570)

Step 4: Add Items to the Ad Group

Endpoint: POST /api/v1/adItems
Response: list of { adItemId, code, details } per item
Conditions / Recommendations:

• Up to a maximum of 10 items can be added to an ad group
• Check code per item in the response — the overall HTTP status is always 200 even when individual items fail
• A minimum of 1 item is required; a minimum of 3 is recommended to avoid stop serving in out-of-stock scenarios
• Pass the itemId exactly as returned by /itemSearch

Step 5: Add Keywords to the Ad Group

Endpoint: POST /api/v1/keywords
Response: keywordIds
Conditions / Recommendations:

• A maximum of 200 distinct bid keywords with 1 to 3 keyword-match types for each can be enabled per ad group
• Keywords are not affected by the US Item ID migration

Step 5: Submit a Review Request

Endpoint: POST /api/v1/review
Response: reviewId, status: submitted
Conditions / Recommendations:

• Ad items and keywords are subject to review approval before the campaign can go live
• Review process can take 1–3 days

Step 6: Fetch Campaign Performance Reports

Endpoint: POST /api/v1/snapshot/report
Response: report download URL or data by reportType
Conditions / Recommendations:

• Specify reportType to select the dimension: adItem, adGroup, platform, pageType, keyword, brand, category, and more
• Report item-level data reflects the US Item ID format for migrated advertisers

---

6.2 Updating Item Bid

flowchart TD
    classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a5f
    classDef decision fill:#fef9c3,stroke:#ca8a04,color:#713f12
    classDef ok fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef fail fill:#fee2e2,stroke:#dc2626,color:#7f1d1d

    START([Update item bid]) --> GET

    GET["GET /api/v1/adItems\ncampaignId"]:::api
    GET -->|"returns adItemId · itemId · bid · status"| PUT

    PUT["PUT /api/v1/adItems\ncampaignId · adGroupId\nitemId · new bid · status"]:::api
    PUT --> CHK{Per-item code}:::decision

    CHK -->|"code: success"| OK["Bid updated immediately\nNo review required\nNew bid active within minutes"]:::ok

    CHK -->|"code: failure"| DETAIL{Check details}:::decision
    DETAIL -->|"Bid should be higher than X\nbid below floor"| FLOOR["Increase bid above floor\nand retry PUT"]:::fail
    DETAIL -->|"ITEMID_NOT_FOUND\nWrong ID format"| IDFAIL["Use itemId from\nGET /adItems response\nnot a constructed value"]:::fail
    FLOOR --> PUT
    IDFAIL --> GET

Step 1: Retrieve Current Item Details

Endpoint: GET /api/v1/adItems
Response: adItemId, itemId, bid, status, reviewStatus

Step 2: Submit Updated Bid

Endpoint: PUT /api/v1/adItems
Conditions / Recommendations:

• Include campaignId, adGroupId, itemId, the new bid value, and status in the request body
• Bid updates do not require a new review — they take effect immediately
• Bids must meet the floor bid threshold; a per-item details message is returned if the bid is too low

---

6.3 SBA Profile Review Workflow

SBA (Search Brand Amplifier) profile creation and review is not affected by the US Item ID migration.

flowchart TD
    classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a5f
    classDef decision fill:#fef9c3,stroke:#ca8a04,color:#713f12
    classDef ok fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef fail fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
    classDef term fill:#f3e8ff,stroke:#7c3aed,color:#3b0764

    START([Ad group created]) --> CREATE

    subgraph PROFILE["SBA Profile Setup"]
        CREATE["POST /api/v1/sba_profile\nadGroupId · headline · brandName\nlogoUrl · clickUrl"]:::api
        CREATE -->|"sbaProfileId\nreviewStatus: pending"| SUBMIT
    end

    subgraph REVIEW["Review Cycle"]
        SUBMIT["POST /api/v1/review\nadGroupId"]:::api
        SUBMIT -->|"reviewId · status: submitted"| POLL
        POLL["GET /api/v1/review\npoll status"]:::api
        POLL --> STATUS{Review status}:::decision

        STATUS -->|"pending or in-progress\npoll again after 30 min"| POLL

        STATUS -->|"rejected\nprofile or items"| REJECT["Review rejection reason\nUpdate profile / items"]:::fail
        REJECT --> CANCEL["PUT /api/v1/review\ncancel current review"]:::api
        CANCEL --> SUBMIT

        STATUS -->|"approved\nall components"| APPROVED
    end

    subgraph LAUNCH["Campaign Eligibility"]
        APPROVED["Profile approved\nAt least 1 item approved\nAt least 1 keyword approved"]:::ok
        APPROVED --> ELIGIBLE{All criteria met?}:::decision
        ELIGIBLE -->|"Yes"| LIVE(["Campaign auto-schedules\nand goes live"]):::term
        ELIGIBLE -->|"No — missing items\nor keywords"| FIX["Add or fix items/keywords\nand re-submit review"]:::fail
        FIX --> SUBMIT
    end

Step 1: Create SBA Profile for the Ad Group

Endpoint: POST /api/v1/sba_profile
Response: sbaProfileId, status: pending
Conditions / Recommendations:

• Provide adGroupId, headline (max 45 characters), brand logo URL, and click URL
• Click URL must be https://www.samsclub.com/*
• Only one SBA profile is allowed per campaign

Step 2: Submit a Review Request

Endpoint: POST /api/v1/review
Response: reviewId, status: submitted
Conditions / Recommendations:

• The SBA profile, ad items, and keywords are all reviewed together
• Review can take 1–3 days

Step 3: Check Review Outcome

Endpoint: GET /api/v1/review
Response: status: approved or status: rejected per component
Conditions / Recommendations:

• If the SBA profile is rejected, update the profile and re-submit for review
• Cancel a pending or in-progress review via PUT /api/v1/review before modifying and re-submitting

---

7. Migration Readiness Checklist

Use this checklist before your advertiser account is enabled for US Item IDs.

• [ ] Item IDs in your system are sourced from API responses (not constructed manually)
• [ ] Your item ID storage field supports 10-digit numeric strings (not only prod-prefixed strings)
• [ ] Your integration checks code per item in POST /adItems responses and handles code: "failure" gracefully
• [ ] You have tested against a staging advertiser account with US Item IDs enabled
• [ ] You use the correct item ID format when calling POST /adItems based on your account's migration status

---

8. Frequently Asked Questions

Q: Do I need to re-add my existing items after migration? No. Existing items are automatically mapped to their US Item ID equivalent. No re-ingestion required.

Q: Can I pass either format and have the API figure it out? No. Once your advertiser is migrated, all item ID inputs must be US Item IDs. Passing a legacy prod-prefixed ID returns a per-item code: "failure" with details: "ITEMID_NOT_FOUND, Input id: ..." in the response.

Q: Will pagination break? No. Pagination tokens and cursors remain format-compatible across the migration.

Q: Are keywords, bid multipliers, or SBA profiles affected? No. Only item-related endpoints (adItems) change behavior.

Q: What happens if I send the wrong format before my account is migrated? Legacy IDs continue to work until your account is migrated or the forced cutover date of July 31, 2026, whichever comes first. After that date, all accounts are migrated and legacy prod-prefixed IDs will no longer be accepted.

---

For integration support, contact the Sam's Club Sponsored Products API partner team.