Order links

Give shoppers a button on their order that opens your app's page for a line, with a signed launch.

An order link is a button under an order line that opens your app's own page for that line: downloads, a licence, a design proof, a booking. You set the page's address on the order item; shoppers see only the button, named after your definition. Tringify shows it on the order status page, the Thank-you page and the account order page, and every click reaches your page with a signed launch naming the store, the order, the line and the customer.

Declare it#

Declare one order_item metafield of type url with buyer_access=read and presentation=order_link. An app has at most one order link. The definition's Name is the button label shoppers see, so name it for what the page gives them, such as Downloads. Any other combination is refused with METAFIELD_DEFINITION_PRESENTATION_ORDER_LINK_INVALID; a second order link with METAFIELD_DEFINITION_PRESENTATION_DUPLICATE. Your app needs read_orders and write_orders.

order-link-declaration.json json
{
  "key":"downloads","name":"Downloads","owner_type":"order_item","type":"url",
  "app_access":"private","merchant_access":"read","buyer_access":"read",
  "presentation":"order_link"
}

Set the address#

When a line is ready, write its page's address with PUT /api/2025-01/orders/{order_id}/items/{item_id}/metafields. Write it for every line the page serves. The address must be HTTPS on one of your app's own origins: its Admin UI URL, a redirect URI, an App Bridge origin or a storefront surface URL in the installed release. A line whose address has another origin shows no button. Shoppers never see or copy the address, so it may carry your own identifiers, but never a secret: the launch is what proves who is asking.

set-order-link.json json
{
  "metafields": [
    { "namespace": "app:my-app", "key": "downloads", "value": "https://files.example.com/orders/downloads" }
  ]
}

Where shoppers see it

Shown when

Order status page

Always, from the link in every order email

Thank-you page

Right after checkout. A row that groups several custom lines shows each order link once.

Account order page

When the theme renders ctx.customer.order.items[].links (see the CTX reference)

A line of a cancelled order, or a line refunded in full, shows no button. Clearing the value removes it. Uninstalling the app removes every button at once.

Handle the launch#

A click posts a form to your address with one field, launch_token: a token signed for your app that expires after two minutes. Exchange it from your server before you return anything, exactly as for a storefront surface:

exchange.sh bash
curl -X POST https://api-store.tringify.com/api/2025-01/runtime/surface-launches/exchange \
  -H "Authorization: Bearer LAUNCH_TOKEN"

Field

For an order link

surface_key, subject

order_link

app_id, audience

Your app and your client ID. Refuse anything else.

store_id, storefront_id

The store and the storefront the shopper clicked on

context.order_id, context.order_item_id, context.order_number

The order and the line the button belongs to

customer_subject

The order's customer, as an identifier only your app receives; absent for a guest order

surface_group_id

The order link's definition ID

A token is exchanged once; a second exchange returns 401. Before you show anything, read the order or line with the store's token if you need more than the launch carries, and check that the line is still one you serve. Show the shopper everything your app has for the whole order, not only the line clicked: a series of custom lines shows one button for all of them.

Emails#

Order emails never carry your address. Once per order, a minute after the first value the shopper can read is set on any of its lines, Tringify sends the Items Ready email (order_items_ready). It lists each line's values; an order link appears as a button to the order status page, where the shopper clicks through to your page. Values set later don't send again: the order page always shows the current ones. Merchants can turn the email off or edit it like any other customer notification.