The public docs mark payment_failed_url as optional on the Campaigns API order-create endpoint, but the live API rejects some requests without it with "This field is required.".
Anchors
- Docs say optional:
content/docs/campaigns/api/index.mdx:142 → // Optional Decline Page
- Spec excludes from required:
public/api/campaigns/v1.yaml:562-567 → CreateOrder.required: [lines, payment_detail, shipping_method, success_url]
- Live API response when the field is missing:
{"message": [{"payment_failed_url": ["This field is required."]}]}
Captured case
wuzutech US nano-cleaning-cloth/v1 checkout — a few rejections per day from /api/v1/orders/ with the above response. Not 100% of traffic, which suggests a conditional requirement (likely payment-method or gateway-flow specific) rather than a blanket one. Same pattern could affect any other hand-coded campaign template that follows the docs as written.
Suggested fix — docs side (easy)
Update content/docs/campaigns/api/index.mdx:142 to mark payment_failed_url as required (or conditionally required, if confirmed), with a one-line note on the condition — likely tied to APM/3DS redirect flows needing a fallback URL. Update the OpenAPI spec at public/api/campaigns/v1.yaml:562-567 to match. If the requirement is conditional on payment method or gateway behavior, document the condition explicitly so merchants building hand-coded checkouts know when they need it.
Alternative — API side (harder)
If the field should genuinely be optional, fix the campaigns-app serializer to actually treat it that way (currently rejecting under certain conditions). Docs/spec already say it's optional, so no docs change needed under this path.
The public docs mark
payment_failed_urlas optional on the Campaigns API order-create endpoint, but the live API rejects some requests without it with"This field is required.".Anchors
content/docs/campaigns/api/index.mdx:142→// Optional Decline Pagepublic/api/campaigns/v1.yaml:562-567→CreateOrder.required: [lines, payment_detail, shipping_method, success_url]{"message": [{"payment_failed_url": ["This field is required."]}]}Captured case
wuzutech US
nano-cleaning-cloth/v1checkout — a few rejections per day from/api/v1/orders/with the above response. Not 100% of traffic, which suggests a conditional requirement (likely payment-method or gateway-flow specific) rather than a blanket one. Same pattern could affect any other hand-coded campaign template that follows the docs as written.Suggested fix — docs side (easy)
Update
content/docs/campaigns/api/index.mdx:142to markpayment_failed_urlas required (or conditionally required, if confirmed), with a one-line note on the condition — likely tied to APM/3DS redirect flows needing a fallback URL. Update the OpenAPI spec atpublic/api/campaigns/v1.yaml:562-567to match. If the requirement is conditional on payment method or gateway behavior, document the condition explicitly so merchants building hand-coded checkouts know when they need it.Alternative — API side (harder)
If the field should genuinely be optional, fix the campaigns-app serializer to actually treat it that way (currently rejecting under certain conditions). Docs/spec already say it's optional, so no docs change needed under this path.