Skip to content

Commit 1bac87c

Browse files
nikolayminev-runanikolayminev-runa
committed
Adding guide on how to use it
1 parent 882da37 commit 1bac87c

File tree

1 file changed

+218
-46
lines changed

1 file changed

+218
-46
lines changed

‎reference/2024-02-05/webhook/product.update.mdx‎

Lines changed: 218 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -25,53 +25,225 @@ Use the `product_code` to identify the product that was updated, then refer to t
2525
the last event you received.
2626
</Info>
2727

28-
## Denomination Structure
29-
30-
The `denominations` object within both `old_state` and `new_state` represents the available purchase amounts for a product. It has the following structure:
31-
32-
### Properties
33-
34-
- `type` - The denomination type, either:
35-
- `"fixed"` - Product has predetermined fixed denominations
36-
- `"open"` - Product accepts any amount within specified range
37-
38-
- `available_list` - Array of strings representing available denomination amounts (only for `"fixed"` type)
39-
40-
- `minimum_value` - String representing the minimum purchase amount (only for `"open"` type)
41-
42-
- `maximum_value` - String representing the maximum purchase amount (only for `"open"` type)
43-
44-
### Usage Examples
45-
46-
#### Fixed Denominations
47-
```json
48-
{
49-
"denominations": {
50-
"type": "fixed",
51-
"available_list": ["10", "25", "50", "100"]
28+
<Warning>
29+
The primary purpose of this webhook is to prevent order failures. Always update your catalog promptly when receiving these events to ensure the best customer experience.
30+
</Warning>
31+
32+
## How to Use This Webhook
33+
34+
This webhook helps you keep your product catalog synchronized with Runa's system and minimize order failures. Here's how to handle each field:
35+
36+
### Product Availability (`is_orderable`)
37+
38+
**When a product becomes non-orderable:**
39+
- **Action:** Immediately disable the product in your catalog
40+
- **Reason:** New orders will be rejected by Runa's system
41+
- **Implementation:** Hide the product from customers or mark as "Currently Unavailable"
42+
- **Example:**
43+
```json
44+
{
45+
"product_code": "AMAZON-US",
46+
"old_state": {
47+
"price_multiplier": "0.0098",
48+
"is_orderable": true,
49+
"denominations": {
50+
"type": "fixed",
51+
"available_list": ["10", "25", "50"],
52+
"minimum_value": "10.0",
53+
"maximum_value": "50.0"
54+
}
55+
},
56+
"new_state": {
57+
"price_multiplier": "0.0098",
58+
"is_orderable": false,
59+
"denominations": {
60+
"type": "fixed",
61+
"available_list": ["10", "25", "50"],
62+
"minimum_value": "10.0",
63+
"maximum_value": "50.0"
64+
}
65+
},
66+
"timestamp": "2025-08-26T18:39:27.006833+00:00"
67+
}
68+
```
69+
70+
**When a product becomes orderable again:**
71+
- **Action:** Re-enable the product in your catalog
72+
- **Reason:** Orders can now be successfully processed
73+
- **Example:**
74+
```json
75+
{
76+
"product_code": "AMAZON-US",
77+
"old_state": {
78+
"price_multiplier": "0.0098",
79+
"is_orderable": false,
80+
"denominations": {
81+
"type": "fixed",
82+
"available_list": ["10", "25", "50"],
83+
"minimum_value": "10.0",
84+
"maximum_value": "50.0"
85+
}
86+
},
87+
"new_state": {
88+
"price_multiplier": "0.0098",
89+
"is_orderable": true,
90+
"denominations": {
91+
"type": "fixed",
92+
"available_list": ["10", "25", "50"],
93+
"minimum_value": "10.0",
94+
"maximum_value": "50.0"
95+
}
96+
},
97+
"timestamp": "2025-08-26T18:39:27.006833+00:00"
98+
}
99+
```
100+
101+
### Pricing Changes (`price_multiplier`)
102+
103+
**When the price multiplier changes:**
104+
- **Action:** Update your product pricing and discounts accordingly
105+
- **Implementation:** Use the new multiplier to calculate updated prices
106+
- **Note:** For detailed pricing questions, contact your account manager
107+
- **Example:**
108+
```json
109+
{
110+
"product_code": "STARBUCKS-US",
111+
"old_state": {
112+
"price_multiplier": "0.0095",
113+
"is_orderable": true,
114+
"denominations": {
115+
"type": "fixed",
116+
"available_list": ["10", "25", "50"],
117+
"minimum_value": "10.0",
118+
"maximum_value": "50.0"
119+
}
120+
},
121+
"new_state": {
122+
"price_multiplier": "0.0090",
123+
"is_orderable": true,
124+
"denominations": {
125+
"type": "fixed",
126+
"available_list": ["10", "25", "50"],
127+
"minimum_value": "10.0",
128+
"maximum_value": "50.0"
129+
}
130+
},
131+
"timestamp": "2025-08-26T18:39:27.006833+00:00"
132+
}
133+
```
134+
135+
### Denomination Updates (`denominations`)
136+
137+
The `denominations` object represents available purchase amounts for a product. There are two types:
138+
139+
- **Fixed denominations** - Predetermined amounts like $10, $25, $50
140+
- **Open denominations** - Any amount within a specified range
141+
142+
**For Fixed Denomination Products:**
143+
144+
**When denominations are removed from `available_list`:**
145+
- **Action:** Remove those denominations from your product options
146+
- **Reason:** Specific denominations are out of stock - orders for these amounts will fail
147+
- **Example:**
148+
```json
149+
{
150+
"product_code": "MSFT-US",
151+
"old_state": {
152+
"price_multiplier": "0.0104",
153+
"is_orderable": true,
154+
"denominations": {
155+
"type": "fixed",
156+
"available_list": ["15", "25", "50", "100"],
157+
"minimum_value": "15.0",
158+
"maximum_value": "100.0"
159+
}
160+
},
161+
"new_state": {
162+
"price_multiplier": "0.0104",
163+
"is_orderable": true,
164+
"denominations": {
165+
"type": "fixed",
166+
"available_list": ["25", "50", "100"],
167+
"minimum_value": "25.0",
168+
"maximum_value": "100.0"
169+
}
170+
},
171+
"timestamp": "2025-08-26T18:39:27.006833+00:00"
52172
}
53-
}
54-
```
55-
56-
#### Open Denominations
57-
```json
58-
{
59-
"denominations": {
60-
"type": "open",
61-
"minimum_value": "5",
62-
"maximum_value": "500"
173+
```
174+
Remove the $15 option from your interface.
175+
176+
**When denominations are added back to `available_list`:**
177+
- **Action:** Re-enable those denomination options
178+
- **Reason:** Stock has been replenished for those amounts
179+
- **Example:**
180+
```json
181+
{
182+
"product_code": "MSFT-US",
183+
"old_state": {
184+
"price_multiplier": "0.0104",
185+
"is_orderable": true,
186+
"denominations": {
187+
"type": "fixed",
188+
"available_list": ["15", "25", "50", "100"],
189+
"minimum_value": "15.0",
190+
"maximum_value": "100.0"
191+
}
192+
},
193+
"new_state": {
194+
"price_multiplier": "0.0104",
195+
"is_orderable": true,
196+
"denominations": {
197+
"type": "fixed",
198+
"available_list": ["5", "15", "25", "50", "100"],
199+
"minimum_value": "5.0",
200+
"maximum_value": "100.0"
201+
}
202+
},
203+
"timestamp": "2025-08-26T18:39:27.006833+00:00"
63204
}
64-
}
65-
```
66-
67-
#### Product Becomes Non-Orderable
68-
```json
69-
{
70-
"denominations": {
71-
"type": "fixed",
72-
"available_list": ["10", "25", "50"]
205+
```
206+
Add the $5 option to your interface.
207+
208+
**For Open Denomination Products:**
209+
210+
**When `minimum_value` or `maximum_value` changes:**
211+
- **Action:** Update your input validation and UI constraints
212+
- **Reason:** Orders outside the new range will be rejected
213+
- **Example:**
214+
```json
215+
{
216+
"product_code": "VISA-PREPAID-US",
217+
"old_state": {
218+
"price_multiplier": "1.0",
219+
"is_orderable": true,
220+
"denominations": {
221+
"type": "open",
222+
"minimum_value": "5",
223+
"maximum_value": "500"
224+
}
225+
},
226+
"new_state": {
227+
"price_multiplier": "1.0",
228+
"is_orderable": true,
229+
"denominations": {
230+
"type": "open",
231+
"minimum_value": "10",
232+
"maximum_value": "300"
233+
}
234+
},
235+
"timestamp": "2024-04-10T17:11:26.601254"
73236
}
74-
}
75-
```
237+
```
238+
Update your form validation to only accept amounts between $10-$300.
239+
240+
**Note:** When a product becomes non-orderable (`is_orderable: false`), both the `denominations` and `price_multiplier` information are preserved and continue to show the same values that were available when the product was orderable.
241+
242+
## Field Reference
243+
244+
### `denominations` Object Structure
76245

77-
When a product becomes non-orderable (`is_orderable: false`), the `denominations.available_list` continues to contain the same denomination values that were available when the product was orderable.
246+
- `type` - The denomination type: `"fixed"` or `"open"`
247+
- `available_list` - Array of available amounts (fixed type only)
248+
- `minimum_value` - Minimum purchase amount (open type only)
249+
- `maximum_value` - Maximum purchase amount (open type only)

0 commit comments

Comments
 (0)