---
updatedAt: 2026-06-25T22:10:43.000Z
---

# 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

```Text bash
POST https://marketplace.walmartapis.com/v3/webhooks/subscriptions
```

## Sample request

```json JSON
curl --request POST \
     --url https://marketplace.walmartapis.com/v3/webhooks/subscriptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
```
```python
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`: Event type to subscribe to (for example, `OFFER_UNPUBLISHED`).
* `eventVersion`: Version of the event type (for example, `V1`).
* `resourceName`: Resource or functional category that the event type is mapped to (for example, `ITEM`, `ORDER`, `PRICE`).
* `eventUrl`: Destination URL where notifications are delivered.
* `headers`: Additional HTTP headers Walmart should include when delivering notifications to your destination URL. Use this field for custom authentication headers, tracking identifiers, or other headers your endpoint requires.
* `status`: Status of the subscription. Notifications are sent only when the subscription is `ACTIVE`. 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

```json JSON
{  
  "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.

<br />