New arguments added to statusPageUrl field on the Order object

We're enhancing the security of order status URLs by replacing static keys with purpose-specific capability tokens. This change helps protect customer data while giving you more control over URL access patterns.

What's changing

Order status URLs now use dynamically generated capability tokens instead of static key parameters. These tokens provide better security through limited use counts and automatic expiration. Unlike the previous approach, where tokens have been stored in a database, these tokens are generated on demand when creating order status URLs. This eliminates the need for token storage and management, providing more security.

How to use the new tokens

When generating order status URLs, you can now specify two optional arguments:

• notification_usage: The delivery channel.
  • WEB (default): For most use cases, including email.
  • SMS
• audience: The intended recipient.
  • CUSTOMERVIEW (default): Intended for a customer. To be sent through a notification and opened at a later time.
  • MERCHANTVIEW: Intended for a merchant. To be used immediately to preview the order status page.

Both of these arguments determine the token's configuration, including expiration. Make sure to choose the right combination to ensure you obtain a token that matches the security profile of your intended use case.

The configuration overview is as follows:

Please note that the token configurations and their use cases may be adjusted in the future based on feedback and evolving security needs. Stay informed about updates to ensure your implementation remains secure and up-to-date.

URL length considerations

When using capability tokens with WEB delivery, the generated URLs will be significantly longer (approximately 800 characters) compared to the previous static key implementation. This increased length is due to the additional security information encoded in the token.

Timeline and backward compatibility

For the next three months, URLs generated without these arguments will continue using the existing secret_token method. After August 1, 2025, all URLs will default to using tokens configured for web customer view.

Next steps

Review your implementation to determine if you need to update your code to specify these arguments based on your use case. Most implementations will work without changes during the transition period.