<!-- x-generated: Generated by the Hyperscale artifact pipeline; do not edit by hand -->

# Personalized Shopping Concierge

> The frozen Personalized Shopping Concierge Product Build, version 1.

- Composition id: `personalized_shopping_concierge`
- Version: 1
- Digest: `cccbf806ef637fd477ddebe4949b941c2a1505a1d21fbce6e8604fb1a40b39cf`
- Currencies: `SAR`
- Webhook events: 25

## Instruments

| Instrument | Title | States | Actions |
| --- | --- | --- | --- |
| [`escrow_order`](../instruments/escrow_order.md) | Escrow order | 9 | create, fund, refund |
| [`listing`](../instruments/listing.md) | Listing | 5 | create, sell |

## Journeys

### Cancel an unfunded escrow

- Journey id: `unfunded_escrow_canceled`
- Steps: 11

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- customer.customerAccessId
3. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- customer.customerId
4. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
5. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- buyer_customer.customerAccessId
6. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- buyer_customer.customerId
7. `subject_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/subjects`, scopes product:write, idempotency required, receipt yes
   - Body: attributes, declaredValue, kind, kindVersion, productId
   - Path: none
   - Query: none
   - Expect: subjectId, tenantId, productId, kind, kindVersion, attributes, declaredValue, createdAt, metadata
   - Bindings: none
8. `listing_create`
   - Actor: product
   - Action: `listing.create`
   - Route: `POST /v1/listings`, scopes listing:write, idempotency required, receipt yes
   - Body: askingPrice, currency, description, expiresAt, headline, imageUrl, productId, sellerAccountId, subject
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: sellerAccountId <- seller.accountId, subject <- subject.subjectId
9. `listing_publish`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/listings/{listingId}/publish`, scopes listing:write, idempotency required, receipt yes
   - Body: none
   - Path: listingId
   - Query: none
   - Expect: none
   - Bindings: listingId <- listing.listingId
10. `escrow_order_create`
   - Actor: product
   - Action: `escrow_order.create`
   - Route: `POST /v1/escrow-orders`, scopes escrow_order:write, idempotency required, receipt yes
   - Body: buyerAccountId, fundBy, listingId, memo, productId, subject
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: buyerAccountId <- buyer.accountId, listingId <- listing.listingId, subject <- subject.subjectId
11. `escrow_order_cancel`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/escrow-orders/{escrowOrderId}/cancel`, scopes escrow_order:write, idempotency required, receipt yes
   - Body: none
   - Path: escrowOrderId
   - Query: none
   - Expect: none
   - Bindings: escrowOrderId <- escrow.escrowOrderId

### Withdraw a draft listing

- Journey id: `withdraw_draft_listing`
- Steps: 6

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- customer.customerAccessId
3. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- customer.customerId
4. `subject_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/subjects`, scopes product:write, idempotency required, receipt yes
   - Body: attributes, declaredValue, kind, kindVersion, productId
   - Path: none
   - Query: none
   - Expect: subjectId, tenantId, productId, kind, kindVersion, attributes, declaredValue, createdAt, metadata
   - Bindings: none
5. `listing_create`
   - Actor: product
   - Action: `listing.create`
   - Route: `POST /v1/listings`, scopes listing:write, idempotency required, receipt yes
   - Body: askingPrice, currency, description, expiresAt, headline, imageUrl, productId, sellerAccountId, subject
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: sellerAccountId <- seller_account.accountId, subject <- subject.subjectId
6. `listing_withdraw`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/listings/{listingId}/withdraw`, scopes listing:write, idempotency required, receipt yes
   - Body: none
   - Path: listingId
   - Query: none
   - Expect: none
   - Bindings: listingId <- listing.listingId

### Onboard a shopper

- Journey id: `concierge_shopper_onboarding`
- Steps: 2

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- shopper.customerAccessId

### Fulfill a merchant order

- Journey id: `concierge_order_fulfillment`
- Steps: 15

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- seller.customerAccessId
3. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- seller.customerId
4. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
5. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- buyer.customerAccessId
6. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- buyer.customerId
7. `sandbox_account_fund`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/account-funding`, scopes transfer:write, idempotency required, receipt yes
   - Body: amount, currency, destinationAccountId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: destinationAccountId <- buyer_account.accountId
8. `subject_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/subjects`, scopes product:write, idempotency required, receipt yes
   - Body: attributes, declaredValue, kind, kindVersion, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
9. `listing_create`
   - Actor: product
   - Action: `listing.create`
   - Route: `POST /v1/listings`, scopes listing:write, idempotency required, receipt yes
   - Body: askingPrice, currency, description, expiresAt, headline, imageUrl, productId, sellerAccountId, subject
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: sellerAccountId <- seller_account.accountId, subject <- subject.subjectId
10. `listing_publish`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/listings/{listingId}/publish`, scopes listing:write, idempotency required, receipt yes
   - Body: none
   - Path: listingId
   - Query: none
   - Expect: none
   - Bindings: listingId <- listing.listingId
11. `escrow_order_create`
   - Actor: product
   - Action: `escrow_order.create`
   - Route: `POST /v1/escrow-orders`, scopes escrow_order:write, idempotency required, receipt yes
   - Body: buyerAccountId, fundBy, listingId, memo, productId, subject
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: buyerAccountId <- buyer_account.accountId, listingId <- listing.listingId, subject <- subject.subjectId
12. `escrow_order_fund`
   - Actor: product
   - Action: `escrow_order.fund`
   - Route: `POST /v1/escrow-orders/{escrowOrderId}/fund`, scopes escrow_order:write, transfer:write, idempotency required, receipt yes
   - Body: none
   - Path: escrowOrderId
   - Query: none
   - Expect: none
   - Bindings: escrowOrderId <- escrow.escrowOrderId
13. `listing_reserve`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/listings/{listingId}/reserve`, scopes listing:write, idempotency required, receipt yes
   - Body: escrowOrderId
   - Path: listingId
   - Query: none
   - Expect: none
   - Bindings: listingId <- listing.listingId, escrowOrderId <- escrow.escrowOrderId
14. `escrow_order_release`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/escrow-orders/{escrowOrderId}/release`, scopes escrow_order:write, transfer:write, idempotency required, receipt yes
   - Body: none
   - Path: escrowOrderId
   - Query: none
   - Expect: none
   - Bindings: escrowOrderId <- escrow.escrowOrderId
15. `listing_sell`
   - Actor: product
   - Action: `listing.sell`
   - Route: `POST /v1/listings/{listingId}/sell`, scopes listing:write, idempotency required, receipt yes
   - Body: none
   - Path: listingId
   - Query: none
   - Expect: none
   - Bindings: listingId <- listing.listingId

### Create a shopper pay-in

- Journey id: `concierge_shopper_pay_in`
- Steps: 8

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- payer.customerAccessId
3. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- payer.customerId
4. `sandbox_account_fund`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/account-funding`, scopes transfer:write, idempotency required, receipt yes
   - Body: amount, currency, destinationAccountId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: destinationAccountId <- source.accountId
5. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
6. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- payee.customerAccessId
7. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- payee.customerId
8. `internal_transfer_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/internal-transfers`, scopes transfer:write, idempotency required, receipt yes
   - Body: amount, currency, destinationAccountId, memo, sourceAccountId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: sourceAccountId <- source.accountId, destinationAccountId <- destination.accountId

### Move purchase funds

- Journey id: `concierge_money_movement`
- Steps: 9

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- payer.customerAccessId
3. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- payer.customerId
4. `sandbox_account_fund`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/account-funding`, scopes transfer:write, idempotency required, receipt yes
   - Body: amount, currency, destinationAccountId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: destinationAccountId <- source.accountId
5. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
6. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- payee.customerAccessId
7. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- payee.customerId
8. `internal_transfer_reserve`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/internal-transfers/reserve`, scopes transfer:write, idempotency required, receipt yes
   - Body: amount, currency, destinationAccountId, memo, sourceAccountId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: sourceAccountId <- source.accountId, destinationAccountId <- destination.accountId
9. `internal_transfer_post`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/internal-transfers/{transferId}/post`, scopes transfer:write, idempotency required, receipt yes
   - Body: none
   - Path: transferId
   - Query: none
   - Expect: none
   - Bindings: transferId <- transfer.transferId

## Cost

Cost table version 2026-09-02.1. Flat amounts are multiplied by the action count; basis points price the meter's moved amount, which an action count does not determine.

| Instrument | Action | Effect | Meter | Flat per action | Rate on meter | 1,000 per month | 100,000 per month | 10,000,000 per month |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `escrow_order` | `collect_penalty` | `moves.transfer.internal` | `transfer.internal.volume_sar` | 0.75 SAR | 11 bps | 750.00 SAR | 75,000.00 SAR | 7,500,000.00 SAR |
| `escrow_order` | `create` | `reads.requires_refs` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| `escrow_order` | `expire` | `schedules.due` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| `escrow_order` | `fund` | `moves.collection.pay_in` | `collection.pay_in.volume_sar` | 2.50 SAR | 16 bps | 2,500.00 SAR | 250,000.00 SAR | 25,000,000.00 SAR |
| `escrow_order` | `fund` | `reads.requires_refs` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| `escrow_order` | `quote` | `holds.quote` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| `escrow_order` | `quote` | `schedules.expiry` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| `escrow_order` | `refund` | `moves.transfer.internal` | `transfer.internal.volume_sar` | 0.75 SAR | 11 bps | 750.00 SAR | 75,000.00 SAR | 7,500,000.00 SAR |
| `escrow_order` | `release` | `moves.transfer.internal` | `transfer.internal.volume_sar` | 0.75 SAR | 11 bps | 750.00 SAR | 75,000.00 SAR | 7,500,000.00 SAR |
| `escrow_order` | `release` | `reads.requires_refs` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| `listing` | `expire` | `schedules.due` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| `listing` | `reopen` | `reads.requires_refs` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| `listing` | `reserve` | `reads.requires_refs` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| `listing` | `sell` | `reads.requires_refs` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| **Total flat** | | | | | | **4,750.00 SAR** | **475,000.00 SAR** | **47,500,000.00 SAR** |