Skip to content
[ ]
Built and supported directly

Shopify checkout, Promotion Vault issuance

An employee store gifted by the program owner. Employees claim rewards, they never pay with cash or a card, and Promotion Vault issues the gift card. The store lists a reward as a digital product, the employee checks out at zero cost, Shopify fires an order paid webhook, and the card is delivered.

All of it is standard Shopify

The store lists a $50 reward as a digital product, the employee checks out at zero cost, Shopify fires an orders/paid webhook, your endpoint calls the Promotion Vault issuance API, and Promotion Vault delivers the card. The only real work is the small service in the middle and the one product setting people get wrong.

No money changes hands

The storefront is gated to invited employees and every reward checks out at $0, so there is no payment gateway, no tender, and nothing to refund in cash.

Shopify is the order of record

A $0 order still fires orders/paid, still carries line item properties, and still accepts a fulfillment, which is what makes it a usable trigger.

Promotion Vault bills the program

The program owner funds the rewards and is billed on activation. Unclaimed rewards cost nothing, and the Shopify order id reconciles the two ledgers.

The full round trip

Nine hops from a claim to a delivered card.

Green is the Shopify contract, gold is the Promotion Vault contract.

Employee CLAIMANT Shopify store GATED + ORDERS Your endpoint CUSTOM APP Promotion Vault ISSUANCE API 1 claims $50 reward, enters recipient email 2 order created at $0, no payment collected 3 webhook orders/paid X-SHOPIFY-HMAC-SHA256 4 200 OK immediately, then work the queue 5 issue card, $50, recipient, program IDEMPOTENCY KEY = ORDER ID 6 card id, activation status 7 reward email with claim link, straight from Promotion Vault 8 fulfillmentCreate plus card reference on the order 9 order shows fulfilled, reference visible
Step 4 is the one with a clock on it: Shopify wants a fast 200 and will retry the delivery for roughly two days if it does not get one, so acknowledge first and issue the card on a queue.

Setting it up in Shopify

1
Build the product as a regular digital item, not a Shopify gift card. This is the trap. Shopify’s native gift card product type mints a Shopify gift card redeemable in that same store, which is not what you are handing out. Create an ordinary product, uncheck the physical product box so no shipping is requested, and use variants for the $25, $50 and $100 denominations.
2
Price the reward at $0 and gate who can reach it. Employees are not buying anything, so the product sits at $0 and no payment method is ever requested. Password protect the storefront, require customer accounts, or use B2B company accounts so only invited employees can claim.
3
Capture the recipient at the product page. Add line item properties to the add to cart form, for example properties[Recipient email] and properties[Message]. They ride through checkout and land on the order payload. Editing the checkout page itself needs Plus, so keeping the fields on the product page keeps every plan in play.
4
Create a custom app and subscribe to orders/paid. Settings, then Apps and sales channels, then Develop apps. Grant the Admin API scopes read_orders and write_fulfillments, then subscribe your HTTPS endpoint to orders/paid. A $0 order is marked paid on completion, so the event still fires and still means the claim is final.
5
Verify, deduplicate, acknowledge, then issue. Check the HMAC header against your app secret before trusting the body. Deduplicate on X-Shopify-Webhook-Id, since retries and redeliveries are normal. Return 200 right away and do the Promotion Vault call on a background job.
6
Map SKU to denomination on your side. Do not let the request tell you the face value, and never read it off the order price, which is $0. Keep a lookup from Shopify variant or SKU to the Promotion Vault denomination and program, so the only thing the order supplies is which SKU was claimed and who it goes to.
7
Write the result back onto the order. Create the fulfillment so the order stops looking open, and store the Promotion Vault card or transaction reference in an order metafield or note. That reference is what makes support questions and month end reconciliation answerable.
8
Handle the unhappy paths. Subscribe to orders/cancelled so a cancelled claim can void or deactivate an unactivated card. Add a reconciliation job that finds orders completed in the last 24 hours with no card reference, because webhook delivery is best effort and should never be your only record.

What the payload looks like

The relevant slice of the Shopify order webhook, and the request it turns into.

In: POST from Shopify
{
  "id": 5432109876543,
  "order_number": 1042,
  "financial_status": "paid",
  "total_price": "0.00",
  "email": "[email protected]",
  "line_items": [{
    "sku": "PV-REWARD-50",
    "quantity": 1,
    "price": "0.00",
    "properties": [
      { "name": "Recipient email",
        "value": "[email protected]" }
    ]
  }]
}
Out: POST to Promotion Vault 3.0
POST https://api3.promotionvault.com/...
Authorization: token YOUR-TOKEN
Content-Type: application/json

{
  "team_id": "<GoodLife rewards team>",
  "amount": 50.00,
  "recipient": { "email": "[email protected]" },
  "external_ref": "shopify-5432109876543"
}
Confirmed against the Promotion Vault 3.0 Public API docs

Base URL is https://api3.promotionvault.com, authentication is token based with an Authorization: token YOUR-TOKEN header, and the token comes from rewards.promotionvault.com/integrations. Rewards are sent from a Team the token has access to, so the Shopify SKU lookup resolves to a Team and an amount rather than a program id. The remaining field names above are still placeholders pending the send reward endpoint spec.

The shape that matters is team, amount, recipient, and a stable external reference that makes a repeated call safe. Note that the amount comes from your SKU lookup, not from the order total.

Things worth deciding early

Trap

The native gift card product type

Selecting it creates a Shopify gift card, not a Promotion Vault one. Two balances, one confused recipient. Use a plain digital product.

Plan

Flow needs a paid tier

The Send HTTP request action lives on Grow, Advanced, and Plus. The custom app route has no plan floor, which usually settles the choice for smaller stores.

Trap

Storefront visible to everyone

This is a gifted employee store, so it has to be gated: password protect the storefront, require customer accounts, or use B2B company accounts so only invited employees can reach the product.

Billing

The claim event is not the activation event

Shopify records a $0 order, Promotion Vault bills the program owner on activation. Keep the card reference on the order so the two ledgers can be lined up at month end.

Ops

Auto fulfill as a backstop

Shopify can automatically fulfill line items after checkout. Useful so digital orders never sit open, but it marks fulfilled whether or not the card actually issued. Keep the reconciliation sweep.

Check

Accounting treatment

Employee rewards can carry payroll implications even when the employee pays nothing. Worth a conversation with your accountant before launch. This is not tax advice.

Effort, honestly

Piece Who does it Rough effort
Product, $0 pricing, and line item properties Store owner or theme developer 1 to 2 hours
Storefront gating for invited employees Store owner, in admin 30 minutes
Custom app and webhook subscription Store owner, in admin 30 minutes
Endpoint: verify, queue, call, fulfill One developer 2 to 4 days
Cancellation and reconciliation handling Same developer 1 to 2 days
Promotion Vault program setup Promotion Vault Standard onboarding

Assumes Promotion Vault exposes a documented issuance endpoint with an idempotency or external reference field. If it does not, that becomes the first line item.

Ready to get started?

Connect with our sales team for a demo or sign up for a free account.