API
Shared Sweeps API
Version 1.0 · Last updated March 2026
The Shared Sweeps API lets your Shopify store display entry counts, retrieve product giveaway settings, and look up order-level entry breakdowns — all in real time.
Production
https://api.sharedsweepsapp.com
QA / Sandbox
https://api-qa.sharedsweepsapp.com
Which URL should I use? We recommend using the
Production URL for all integrations. The production app is
stable, fully supported, and includes features like
product settings migration that are not available in the
QA app.
The QA app and its corresponding base URL are intended for internal beta testing only — it may receive breaking changes at any time and is not recommended for building against. Only use it if you have been explicitly asked to test a pre-release feature.
The QA app and its corresponding base URL are intended for internal beta testing only — it may receive breaking changes at any time and is not recommended for building against. Only use it if you have been explicitly asked to test a pre-release feature.
Contents
Authentication
The Authorization header is required by the API schema but
authentication is not enforced yet. For now, simply pass
any non-empty string as the Bearer token — the value will be ignored.
Authorization: Bearer any-value
📣 Heads up. Real authentication is coming in a future
release. When it is ready, you will be notified in advance with full
migration instructions so you can update your integration before it takes
effect. No action is required from you today — just include the header with
any placeholder value.
Common Request Headers
| Header | Required | Description | Example |
|---|---|---|---|
Authorization |
Yes | JWT Bearer token | Bearer eyJhbGc... |
X-Shopify-Shop-Domain |
Yes | Your Shopify store domain | yourstore.myshopify.com |
Content-Type |
POST only | Must be application/json for POST requests |
application/json |
X-Order-Id |
Endpoint-specific | Shopify order GID (required by order endpoints) | gid://shopify/Order/123 |
Error Handling
All errors return a JSON body with an error field:
{ "error": "Description of what went wrong" }
| Error Message | Cause | Action |
|---|---|---|
Unauthorized |
Invalid or missing JWT token | Check your Authorization header |
Missing shop domain |
Missing X-Shopify-Shop-Domain
|
Add the required header |
Order not found |
Order doesn't exist in Shopify | Verify the order ID |
No active giveaway found for the shop |
No active giveaway configured | Contact support to set up a giveaway |
Endpoints
GET
/products/settings
Returns the giveaway settings for all products in your store, including per-product entry multipliers, bonus entry amounts, active discount-code bonuses, and cart-subtotal thresholds.
⚡ Response caching.
This endpoint caches responses for 2 minutes. Changes
made to product settings (multipliers, bonus entries, coupon codes) may
take up to 2 minutes to reflect in the API response.
🚧 Coming soon — multi-giveaway support.
A new version of this endpoint is currently in development that will
allow fetching settings scoped to each individual giveaway. Today, all
giveaways share a single set of product settings. Once released, the
giveawayId parameter will return settings specific to that
giveaway rather than the global shared settings.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
giveawayId |
integer | optional | Fetch settings for a specific giveaway. Defaults to the currently active giveaway. |
Example Request
curl -X GET
"https://api-qa.sharedsweepsapp.com/products/settings?giveawayId=1" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "X-Shopify-Shop-Domain:
yourstore.myshopify.com"
Example Response — 200 OK
{ "giveawayMultiplier": 1, "products": [ { "productId":
"gid://shopify/Product/123456", "multiplier": 2, "bonusEntries": 10,
"isEligible": true, "updatedAt": "2025-12-08T00:00:00.000Z" } ],
"couponCodes": { "SAVE10": 5, "WELCOME": 10 },
"activeBonusEntryThresholds": [ { "subtotal": 100, "bonusEntries": 50,
"startDate": "2025-01-01T00:00:00.000Z", "endDate":
"2025-12-31T23:59:59.000Z" } ], "isActive": true, "shop":
"yourstore.myshopify.com" }
Response Fields
| Field | Type | Description |
|---|---|---|
giveawayMultiplier |
number | Global entry multiplier applied to all purchases |
products |
array | Per-product settings (see below) |
products[].productId |
string | Shopify product GID |
products[].multiplier |
number | Entry multiplier for this product |
products[].bonusEntries |
number | Flat bonus entries awarded when product is purchased |
products[].isEligible |
boolean | Whether the product earns entries |
couponCodes |
object | Map of coupon code → bonus entries granted when used |
activeBonusEntryThresholds |
array | Cart subtotal thresholds that grant bonus entries |
isActive |
boolean | Whether the giveaway is currently active |
POST
/products/settings/batch/
Retrieve settings for multiple products in a single call. Ideal for storefront apps that need to display entry information for a collection of products at once.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
productIds |
string[] | required | Array of Shopify product GIDs |
giveawayId |
string | optional | Giveaway ID to scope settings to |
Example Request
curl -X POST
"https://api-qa.sharedsweepsapp.com/products/settings/batch/" \ -H
"Authorization: Bearer YOUR_JWT_TOKEN" \ -H "X-Shopify-Shop-Domain:
yourstore.myshopify.com" \ -H "Content-Type: application/json" \ -d '{
"productIds": [ "gid://shopify/Product/123456",
"gid://shopify/Product/789012" ], "giveawayId": "1" }'
Example Response — 200 OK
{ "products": [ { "productId": "gid://shopify/Product/123456",
"isEligible": true, "multiplier": 2, "bonusEntries": 10 }, {
"productId": "gid://shopify/Product/789012", "isEligible": false,
"multiplier": 1, "bonusEntries": 0 } ], "couponCodes": { "SAVE10": 5 }
}
GET
/customers/{customerId}/entries
Returns the total entries earned by a customer, along with a transaction-level breakdown and the associated Shopify orders. Use this to power entry-count widgets on account pages or post-purchase confirmation screens.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
customerId |
string |
Shopify Customer GID — e.g.
gid://shopify/Customer/123456
|
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
giveawayId |
integer | optional | Filter results to a specific giveaway |
Example Request
curl -X GET \
"https://api-qa.sharedsweepsapp.com/customers/gid://shopify/Customer/123456/entries?giveawayId=1"
\ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H
"X-Shopify-Shop-Domain: yourstore.myshopify.com"
Example Response — 200 OK
{ "customerID": "gid://shopify/Customer/123456", "shop":
"yourstore.myshopify.com", "totalEntriesEarned": 150, "wallets": [ {
"giveawayID": 1, "entriesEarned": 50, "createdAt":
"2025-12-01T10:30:00.000Z", "orderID": "gid://shopify/Order/789012" }
], "orders": [ { "id": "gid://shopify/Order/789012", "createdAt":
"2025-12-01T10:00:00.000Z", "totalPrice": "99.99" } ] }
Response Fields
| Field | Type | Description |
|---|---|---|
totalEntriesEarned |
number | Sum of all entries earned across all orders |
wallets |
array | One record per qualifying order showing entries per giveaway |
orders |
array | Shopify order details corresponding to wallet entries |
POST
/get-entries-for-order
Returns the calculated entries for a specific order without writing anything to the database. Use this for previewing entry calculations or debugging configurations.
Additional Headers
| Header | Required | Description |
|---|---|---|
X-Order-Id |
required |
Shopify Order GID — e.g. gid://shopify/Order/123456
|
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
giveawayId |
integer | optional | Evaluate against a specific giveaway |
Example Request
curl -X POST
"https://api-qa.sharedsweepsapp.com/get-entries-for-order" \ -H
"Authorization: Bearer YOUR_JWT_TOKEN" \ -H "X-Shopify-Shop-Domain:
yourstore.myshopify.com" \ -H "X-Order-Id: gid://shopify/Order/123456"
\ -H "Content-Type: application/json" \ -d '{ "giveawayId": 1 }'
Example Response — 200 OK
{ "data": { "entriesEarned": 50, "orderID":
"gid://shopify/Order/123456", "breakdown": { "baseEntries": 10,
"productMultipliers": 30, "bonusEntries": 10 } } }
Response Fields
| Field | Type | Description |
|---|---|---|
data.entriesEarned |
number | Total entries this order earns |
data.breakdown.baseEntries |
number | Base entries from the giveaway rate |
data.breakdown.productMultipliers |
number | Entries added by product-level multipliers |
data.breakdown.bonusEntries |
number | Entries from coupon codes or subtotal thresholds |
HTTP Status Codes
| Code | Meaning |
|---|---|
| 200 | Success — response body contains requested data |
| 204 | No Content — request succeeded but there is nothing to return (e.g. order outside giveaway period) |
| 400 | Bad Request — missing or invalid parameters |
| 401 | Unauthorized — invalid or missing token |
| 404 | Not Found — resource does not exist |
| 409 | Conflict — business logic error (e.g. no active giveaway) |
| 500 | Internal Server Error — contact support if this persists |
CORS
All endpoints support Cross-Origin Resource Sharing for use in browser-based storefronts and Shopify theme extensions.
| Property | Value |
|---|---|
| Allowed Origins | * |
| Allowed Methods |
GET, POST, OPTIONS
|
| Allowed Headers |
Content-Type, Authorization,
X-Shopify-Shop-Domain, X-Order-Id
|
| Credentials | Supported |
Support
For API access, questions, or to report an issue:
Email:
dev@sharedsweeps.com
Shared Sweeps API v1.0 · © 2026 Shared Sweeps