Create subscription

Use the Create subscription API to register a webhook for a specific event (for example, OFFER_UNPUBLISHED). You provide your delivery URL, headers, and authentication details; the service returns the created subscription with a unique subscriptionId along with the current status and the event’s metadata (eventType, eventVersion, resourceName). This endpoint is typically used when onboarding a new webhook, enabling additional event types, or programmatically managing subscriptions across environments.

How it works

1. You send POST /v3/webhooks/subscriptions with a JSON body describing the subscription.
2. Walmart validates your payload and stores the configuration.
3. A 200 response returns an events array containing the created subscription (including subscriptionId and status).

• Common enums: status (Allowed values: ACTIVE, INACTIVE), eventVersion (example: V1), authMethod (example: BASIC_AUTH).

Endpoint

POST https://marketplace.walmartapis.com/v3/webhooks/subscriptions

Sample request

curl --request POST \ --url https://marketplace.walmartapis.com/v3/webhooks/subscriptions \ --header 'accept: application/json' \ --header 'content-type: application/json'

import requests url = "https://marketplace.walmartapis.com/v3/webhooks/subscriptions" headers = { "Accept": "application/json", "Content-Type": "application/json", # "Authorization": "Basic <base64-username:password>", # if required
} # Example body (edit to your needs or set to {} if you truly have no body)
payload = { "eventType": "OFFER_UNPUBLISHED", "eventVersion": "V1", "resourceName": "ITEM", "eventUrl": "https://example.com/events", "headers": { "content-type": "application/json" }, "authDetails": { "authMethod": "BASIC_AUTH", "authHeaderName": "Authorization", "userName": "abc", "password": "test" }, "status": "ACTIVE"
} resp = requests.post(url, headers=headers, json=payload, timeout=30)
resp.raise_for_status() # raises if not 2xx
print(resp.status_code)
print(resp.json())

Modify your code

Follow these steps to customize your request so it returns 200 OK and creates the subscription you expect:

1. Set headers and add the OAuth 2.0 bearer token in the Authorization header of your request.
2. Define the subscription body

• eventType: The event you want (for example, OFFER_UNPUBLISHED).
• eventVersion: API event schema version (for example, V1).
• resourceName: Resource associated with the event (for example, ITEM, ORDER, PRICE).
• eventUrl: Your HTTPS endpoint to receive callbacks.
• headers: Any headers Walmart should include when delivering events (for example, content-type).
• status: Use ACTIVE to begin receiving events, or INACTIVE to create it disabled.

3. Validate success criteria

• HTTP status: 200 OK
• Body: JSON with an events array containing your new subscription (check subscriptionId, status, and fields you sent).

4. Handle transient errors: On 429 or 5xx, retry with exponential backoff and random jitter. Log only non-sensitive request metadata (timestamp, path, status, duration, attempt, backoff delay) and do not include credentials.

Sample response

{ "events": [ { "eventType": "OFFER_UNPUBLISHED", "subscriptionId": "620b45a0-b321-11ea-ac13-1f88d6025b7d", "partnerId": "12300000359", "eventVersion": "V1", "resourceName": "ITEM", "status": "ACTIVE" } ] }

Next steps

• Use All subscriptions (GET /v3/webhooks/subscriptions) to verify your new subscription.
• Send a Test notification (POST /v3/webhooks/test) to confirm your endpoint returns 2xx.