Scopes

Every REST API key carries a list of scopes that controls which endpoints it can call. The merchant sets them when creating the key in Shopify admin → Apps → Yuko Loyalty → Integrations → REST API:

Full Access Key: the highest access level each scope supports (read and write where available).
Read-Only Key: read access for every scope.
Custom Key: No Access, Read Access or Read/Write Access per scope.

Scope format

Scopes are stored on the key as read:<scope> or write:<scope>, for example read:rewards or write:transactions.

read:<scope> allows the scope’s read endpoints.
write:<scope> allows the scope’s write endpoints and its read endpoints. Write implies read.

Available scopes

Scope	Label in Yuko	Access levels	What it allows
`customers`	Customers	read, write	View customer profiles and points balances
`orders`	Orders	write	Not used by any endpoint in this reference
`rewards`	Rewards	read, write	View the reward catalogue and redeem points for rewards
`transactions`	Transactions	read, write	View points transaction history and manually adjust points
`activities`	Activities	read	View the customer loyalty activity log
`tiers`	Tiers	read	View VIP tier configuration and customer tier status
`earning_rules`	Earning Rules	read	View points earning rules
`referrals`	Referrals	read	View the referral program configuration and customer referrals
`points`	Points	read	Estimate the points a cart will earn (checkout integrations)
`booster_campaigns`	Booster Campaigns	read, write	View active booster campaigns (no write endpoints yet)

Endpoints by scope

Endpoint	Required scope
`GET /customers`	`read:customers`
`GET /customers/{id}`	`read:customers`
`GET /customers/balance`	`read:customers`
`GET /customers/memberships`	`read:customers`
`GET /customers/tiers`	`read:tiers`
`GET /customers/activities`	`read:activities`
`GET /customers/referrals`	`read:referrals`
`GET /customers/rewards`	`read:rewards`
`GET /customers/rewards/redeemable`	`read:rewards`
`POST /customers/rewards/redeem`	`write:rewards`
`GET /customers/transactions`	`read:transactions`
`POST /customers/transactions`	`write:transactions`
`GET /rewards`	`read:rewards`
`GET /rewards/{id}`	`read:rewards`
`GET /tiers`	`read:tiers`
`GET /earning-rules`	`read:earning_rules`
`GET /referrals/program`	`read:referrals`
`POST /points/estimate`	`read:points`
`GET /booster-campaigns`	`read:booster_campaigns`

All paths are relative to https://api.yukoapp.com/api/v1/public.

Missing scope errors

If the key doesn’t have the scope an endpoint needs, the API returns 403 Forbidden:

403

{
  "error": {
    "code": "insufficient_scope",
    "message": "Your API token does not have the required 'rewards' scope for this action"
  }
}

To fix it, create a new key with the scope you need (or ask the merchant to), then revoke the old key. A key’s scopes can’t be changed after it’s created.

Rest API

API References

Object Reference

Scope format

Available scopes

Endpoints by scope

Missing scope errors

​Scope format

​Available scopes

​Endpoints by scope

​Missing scope errors

Scope format

Available scopes

Endpoints by scope

Missing scope errors