Zwely API

Build against checkout, licensing, and sales data.

Use the REST API to keep product metadata synced, read customers and orders, manage promotions, and validate license keys for the software you sell.

Manage API keys
Reference

Account endpoints are scoped to the API-key owner. Client-safe license validation is scoped to the product bound to the zvl_ token. List endpoints are paginated and return data, links, and meta.

Getting started

Authentication, responses, and safety

Account API keys use bearer authentication and should only be stored on trusted servers. Never embed a zwy_ key in shipped software.

For software activation, create a product-scoped zvl_ validation token from Account API Keys and use the client-safe validation endpoint.

Rate limits are designed for ecommerce integrations that poll responsibly, sync in batches, and retry with backoff. Write requests use a stricter bucket and also count toward the general account API limit.

Account API
120 requests/minute
Writes
30 requests/minute
Client license validation
60 requests/minute
Invalid license attempts
20 requests/minute
  • Send Accept: application/json and authenticate with a bearer token on every API request.
  • Account API and write limits are keyed by the authenticated zwy_ API key.
  • Client-safe license validation is keyed by the zvl_ validation token and request IP.
  • Failed authentication is limited to 20 attempts per minute per IP.
  • Invalid license validation attempts are limited separately to slow brute-force key guessing.
  • Errors use JSON responses: 401 for missing or invalid tokens, 404 for missing or cross-account resources, 422 for validation errors, and 429 with Retry-After when limited.
Product object

Products

Products are the digital goods you sell through Zwely checkout buttons. They hold pricing, product copy, checkout button styling, discount eligibility, and delivery settings. A product can be a single product or a bundle shell that sells multiple existing products together.

  • Use products to keep your external catalog, storefront, or internal admin tools in sync with Zwely.
  • The API manages product metadata only. Delivery files, product images, and license key pools stay managed in the Zwely app in v1.
  • Bundles require at least two existing non-bundle products before creation. Bundle membership, including the list and order of included products, is managed in the Zwely app in v1.
  • Product type is immutable after creation. If you need a bundle instead of a regular product, create a new bundle product.
GET /api/v1/products

List products

Use this endpoint to mirror your Zwely product catalog into another admin tool, storefront, analytics pipeline, or fulfillment system.

Inputs
page query
Optional

Page number to fetch from the paginated collection. Defaults to 1.

per_page query
Optional

Number of records to return per page. Defaults to 25 and is capped at 100.

Returns
A paginated list of Product objects with price, checkout button settings, delivery status, and license inventory counts.
Auth
Account API key
Response properties
data[] array

Array of Product objects for the requested page.

links object

Pagination URLs for first, last, previous, and next pages.

meta object

Pagination metadata including current_page, per_page, total, and last_page.

data[].id string

Public product UUID. Use this as product_id in path parameters and license validation.

data[].product_type string

Product kind: product for a single product, or bundle for a bundle shell. Product type is chosen at creation and cannot be changed later.

data[].title string

Customer-facing product name.

data[].description string|null

Product description shown in checkout and admin views.

data[].price_cents integer

Current product price in cents.

data[].original_price_cents integer|null

Optional compare-at price in cents.

data[].allow_discount_codes boolean

Whether checkout accepts discount codes for this product.

data[].auto_tags array<string>

Normalized product tags.

data[].requires_license boolean

Whether this product uses license key delivery.

data[].generate_license_keys_when_empty boolean

Whether Zwely can generate license keys when the imported pool is empty.

data[].license_keys.total integer

Total license keys attached to the product.

data[].license_keys.used integer

License keys already assigned by checkout.

data[].license_keys.remaining integer

Available license keys remaining.

data[].delivery.has_file boolean

For products, whether a delivery file is attached in Zwely. For bundles, whether bundle product selection has been completed.

data[].delivery.file_name string|null

Original delivery file name when present.

data[].delivery.bundle_product_count integer|null

For bundles, the number of included products when the count is loaded. Regular products omit this value.

data[].image_url string|null

Public image URL when a product image is attached.

data[].checkout_button.text string|null

Embedded checkout button label.

data[].checkout_button.color string|null

Embedded checkout button hex color.

data[].checkout_button.border_radius integer|null

Embedded checkout button corner radius.

data[].checkout_button.padding integer|null

Embedded checkout button padding value.

data[].checkout_button.font_size integer|null

Embedded checkout button font size.

data[].checkout_button.font_family string|null

Embedded checkout button and modal accent font family.

data[].checkout_button.effect string

Embedded checkout button effect. Values include none, sparkle, rainbow-glow, and shimmer.

data[].created_at string|null

ISO timestamp for creation.

data[].updated_at string|null

ISO timestamp for last update.

GET /api/v1/products/{product_id}

Retrieve a product

Fetch one product when you need fresh pricing, availability, license inventory, or checkout button settings before rendering a custom interface.

Inputs
product_id path
Required

Product UUID returned as id by the API. Internal integer IDs are never exposed.

Returns
A single Product object.
Auth
Account API key
Response properties
data.id string

Public product UUID. Use this as product_id in path parameters and license validation.

data.product_type string

Product kind: product for a single product, or bundle for a bundle shell. Product type is chosen at creation and cannot be changed later.

data.title string

Customer-facing product name.

data.description string|null

Product description shown in checkout and admin views.

data.price_cents integer

Current product price in cents.

data.original_price_cents integer|null

Optional compare-at price in cents.

data.allow_discount_codes boolean

Whether checkout accepts discount codes for this product.

data.auto_tags array<string>

Normalized product tags.

data.requires_license boolean

Whether this product uses license key delivery.

data.generate_license_keys_when_empty boolean

Whether Zwely can generate license keys when the imported pool is empty.

data.license_keys.total integer

Total license keys attached to the product.

data.license_keys.used integer

License keys already assigned by checkout.

data.license_keys.remaining integer

Available license keys remaining.

data.delivery.has_file boolean

For products, whether a delivery file is attached in Zwely. For bundles, whether bundle product selection has been completed.

data.delivery.file_name string|null

Original delivery file name when present.

data.delivery.bundle_product_count integer|null

For bundles, the number of included products when the count is loaded. Regular products omit this value.

data.image_url string|null

Public image URL when a product image is attached.

data.checkout_button.text string|null

Embedded checkout button label.

data.checkout_button.color string|null

Embedded checkout button hex color.

data.checkout_button.border_radius integer|null

Embedded checkout button corner radius.

data.checkout_button.padding integer|null

Embedded checkout button padding value.

data.checkout_button.font_size integer|null

Embedded checkout button font size.

data.checkout_button.font_family string|null

Embedded checkout button and modal accent font family.

data.checkout_button.effect string

Embedded checkout button effect. Values include none, sparkle, rainbow-glow, and shimmer.

data.created_at string|null

ISO timestamp for creation.

data.updated_at string|null

ISO timestamp for last update.

PATCH /api/v1/products/{product_id}

Update a product

Patch product metadata when price, positioning, tags, or checkout button copy changes in your external catalog.

  • product_type cannot be changed with PATCH.
Inputs
product_id path
Required

Product UUID returned as id by the API. Internal integer IDs are never exposed.

title body
Optional

Customer-facing product name. Maximum 120 characters.

product_type body
Optional

Product kind. Use product for a single product or bundle for a bundle shell. Defaults to product. The type cannot be changed after creation; bundle creation requires at least two existing non-bundle products, and bundle membership is managed in the Zwely app in v1.

description body
Optional

Product description shown in checkout and admin views. Maximum 800 characters.

price_cents body
Optional

Current price in cents. Use 3900 for $39.00.

original_price_cents body
Optional

Optional compare-at price in cents. Must be greater than price_cents when set.

allow_discount_codes body
Optional

Boolean that controls whether checkout accepts discount codes for this product.

auto_tags body
Optional

Array of up to 12 product tags. Each tag is normalized, deduplicated, and limited to 32 characters.

button_text body
Optional

Checkout button label. Maximum 40 characters.

button_color body
Optional

Hex color for the embedded checkout button, such as #fd614c.

button_border_radius body
Optional

Button corner radius in pixels. Allowed range is 0 to 32.

button_padding body
Optional

Button vertical padding value. Allowed range is 8 to 26.

button_font_size body
Optional

Button font size in pixels. Allowed range is 13 to 22.

button_font_family body
Optional

Google font family used by the checkout button and checkout modal headline/buttons. Use one of the supported Zwely font options, such as Rubik, Manrope, Sora, Playfair Display, or Space Grotesk.

button_effect body
Optional

Optional checkout button effect. Use none for a clean button, sparkle for twinkling yellow sparkles, rainbow-glow for a pulsing color-spectrum glow, or shimmer for a diagonal light sweep around the embedded button and modal payment button.

Returns
The updated Product object.
Auth
Account API key
Response properties
data.id string

Public product UUID. Use this as product_id in path parameters and license validation.

data.product_type string

Product kind: product for a single product, or bundle for a bundle shell. Product type is chosen at creation and cannot be changed later.

data.title string

Customer-facing product name.

data.description string|null

Product description shown in checkout and admin views.

data.price_cents integer

Current product price in cents.

data.original_price_cents integer|null

Optional compare-at price in cents.

data.allow_discount_codes boolean

Whether checkout accepts discount codes for this product.

data.auto_tags array<string>

Normalized product tags.

data.requires_license boolean

Whether this product uses license key delivery.

data.generate_license_keys_when_empty boolean

Whether Zwely can generate license keys when the imported pool is empty.

data.license_keys.total integer

Total license keys attached to the product.

data.license_keys.used integer

License keys already assigned by checkout.

data.license_keys.remaining integer

Available license keys remaining.

data.delivery.has_file boolean

For products, whether a delivery file is attached in Zwely. For bundles, whether bundle product selection has been completed.

data.delivery.file_name string|null

Original delivery file name when present.

data.delivery.bundle_product_count integer|null

For bundles, the number of included products when the count is loaded. Regular products omit this value.

data.image_url string|null

Public image URL when a product image is attached.

data.checkout_button.text string|null

Embedded checkout button label.

data.checkout_button.color string|null

Embedded checkout button hex color.

data.checkout_button.border_radius integer|null

Embedded checkout button corner radius.

data.checkout_button.padding integer|null

Embedded checkout button padding value.

data.checkout_button.font_size integer|null

Embedded checkout button font size.

data.checkout_button.font_family string|null

Embedded checkout button and modal accent font family.

data.checkout_button.effect string

Embedded checkout button effect. Values include none, sparkle, rainbow-glow, and shimmer.

data.created_at string|null

ISO timestamp for creation.

data.updated_at string|null

ISO timestamp for last update.

message string

Confirmation message for the update action.

Customer object

Customers

Customers are buyers or free-claim recipients created by checkout activity. Zwely keeps customer records account-scoped and attaches order history, tags, billing geography, and acquisition page data.

  • Customer endpoints are read-only so checkout remains the source of truth for buyer creation.
  • Use them for CRM syncs, support tooling, customer enrichment, and lifecycle reporting.
GET /api/v1/customers

List customers

Pull customers into your CRM, support dashboard, or analytics warehouse. The response includes order counts and lifetime order total when available.

Inputs
page query
Optional

Page number to fetch from the paginated collection. Defaults to 1.

per_page query
Optional

Number of records to return per page. Defaults to 25 and is capped at 100.

Returns
A paginated list of Customer objects.
Auth
Account API key
Response properties
data[] array

Array of Customer objects for the requested page.

links object

Pagination URLs for first, last, previous, and next pages.

meta object

Pagination metadata including current_page, per_page, total, and last_page.

data[].id string

Public customer UUID.

data[].email string

Customer email collected at checkout.

data[].name string|null

Customer name when available.

data[].phone string|null

Customer phone when available.

data[].billing_country string|null

Billing country from checkout or payment details.

data[].billing_region string|null

Billing region or state when available.

data[].tags array<string>

Customer tags stored in Zwely.

data[].first_checkout_page_url string|null

First checkout page URL where Zwely saw this customer.

data[].first_checkout_page_domain string|null

Domain of the first checkout page.

data[].latest_checkout_page_url string|null

Most recent checkout page URL.

data[].latest_checkout_page_domain string|null

Domain of the most recent checkout page.

data[].latest_order_at string|null

ISO timestamp of the customer’s latest order.

data[].orders_count integer

Number of orders attached to this customer.

data[].orders_total_cents integer

Lifetime order total in cents.

data[].created_at string|null

ISO timestamp for creation.

data[].updated_at string|null

ISO timestamp for last update.

GET /api/v1/customers/{customer_id}

Retrieve a customer

Fetch one customer profile for a support view, entitlement check, or internal buyer detail page.

Inputs
customer_id path
Required

Customer UUID returned as id by the API.

Returns
A single Customer object.
Auth
Account API key
Response properties
data.id string

Public customer UUID.

data.email string

Customer email collected at checkout.

data.name string|null

Customer name when available.

data.phone string|null

Customer phone when available.

data.billing_country string|null

Billing country from checkout or payment details.

data.billing_region string|null

Billing region or state when available.

data.tags array<string>

Customer tags stored in Zwely.

data.first_checkout_page_url string|null

First checkout page URL where Zwely saw this customer.

data.first_checkout_page_domain string|null

Domain of the first checkout page.

data.latest_checkout_page_url string|null

Most recent checkout page URL.

data.latest_checkout_page_domain string|null

Domain of the most recent checkout page.

data.latest_order_at string|null

ISO timestamp of the customer’s latest order.

data.orders_count integer

Number of orders attached to this customer.

data.orders_total_cents integer

Lifetime order total in cents.

data.created_at string|null

ISO timestamp for creation.

data.updated_at string|null

ISO timestamp for last update.

Order object

Orders

Orders are completed checkout records. They connect products, customers, optional discounts, optional license keys, gross revenue, refunds, Stripe fees, and Zwely application fees.

  • Orders are read-only through the API because payment state is controlled by checkout and Stripe.
  • Use orders for fulfillment audit trails, finance exports, dashboards, and customer support.
GET /api/v1/orders

List orders

Sync recent checkouts into your warehouse, fulfillment monitor, customer support queue, or revenue reporting system.

Inputs
page query
Optional

Page number to fetch from the paginated collection. Defaults to 1.

per_page query
Optional

Number of records to return per page. Defaults to 25 and is capped at 100.

Returns
A paginated list of Order objects with related product, customer, discount, payment, and fee summaries.
Auth
Account API key
Response properties
data[] array

Array of Order objects for the requested page.

links object

Pagination URLs for first, last, previous, and next pages.

meta object

Pagination metadata including current_page, per_page, total, and last_page.

data[].id string

Public order UUID.

data[].status string

Order status, such as completed, refunded, or failed.

data[].customer_email string

Email used at checkout.

data[].subtotal_cents integer|null

Subtotal before discounts in cents.

data[].discount_amount_cents integer|null

Discount amount applied in cents.

data[].amount_cents integer

Final charged amount in cents.

data[].refunded_amount_cents integer

Amount refunded in cents.

data[].currency string

Three-letter lowercase currency code.

data[].fees.stripe_fee_cents integer|null

Total Stripe fee recorded for the order.

data[].fees.stripe_processing_fee_cents integer|null

Stripe processing fee portion when known.

data[].fees.application_fee_cents integer|null

Zwely application fee recorded for the order.

data[].fees.creator_net_cents integer|null

Estimated net amount to the seller.

data[].product.id string|null

Product UUID when loaded.

data[].product.title string|null

Product title when loaded.

data[].customer.id string|null

Customer UUID when loaded.

data[].customer.email string|null

Customer email when loaded.

data[].customer.name string|null

Customer name when available.

data[].discount.id string|null

Discount UUID when a code was applied.

data[].discount.code string|null

Discount code applied at checkout.

data[].license_key.assigned boolean|null

True when a license key was assigned.

data[].license_key.created_at string|null

ISO timestamp for license key creation.

data[].license_key.assigned_at string|null

ISO timestamp when checkout assigned the key.

data[].payment.type string|null

Payment method type reported by Stripe.

data[].payment.wallet string|null

Wallet type when a wallet was used.

data[].payment.card_brand string|null

Card brand when available.

data[].payment.card_funding string|null

Card funding type when available.

data[].payment.card_country string|null

Card issuing country when available.

data[].payment.card_last4 string|null

Last four digits of the card when available.

data[].payment.receipt_url string|null

Stripe receipt URL when available.

data[].completed_at string|null

ISO timestamp when checkout completed.

data[].refunded_at string|null

ISO timestamp when the order was refunded.

data[].created_at string|null

ISO timestamp for creation.

data[].updated_at string|null

ISO timestamp for last update.

GET /api/v1/orders/{order_id}

Retrieve an order

Look up a specific order by UUID for support, refund investigation, license assignment inspection, or reconciliation.

Inputs
order_id path
Required

Order UUID returned as id by the API.

Returns
A single Order object.
Auth
Account API key
Response properties
data.id string

Public order UUID.

data.status string

Order status, such as completed, refunded, or failed.

data.customer_email string

Email used at checkout.

data.subtotal_cents integer|null

Subtotal before discounts in cents.

data.discount_amount_cents integer|null

Discount amount applied in cents.

data.amount_cents integer

Final charged amount in cents.

data.refunded_amount_cents integer

Amount refunded in cents.

data.currency string

Three-letter lowercase currency code.

data.fees.stripe_fee_cents integer|null

Total Stripe fee recorded for the order.

data.fees.stripe_processing_fee_cents integer|null

Stripe processing fee portion when known.

data.fees.application_fee_cents integer|null

Zwely application fee recorded for the order.

data.fees.creator_net_cents integer|null

Estimated net amount to the seller.

data.product.id string|null

Product UUID when loaded.

data.product.title string|null

Product title when loaded.

data.customer.id string|null

Customer UUID when loaded.

data.customer.email string|null

Customer email when loaded.

data.customer.name string|null

Customer name when available.

data.discount.id string|null

Discount UUID when a code was applied.

data.discount.code string|null

Discount code applied at checkout.

data.license_key.assigned boolean|null

True when a license key was assigned.

data.license_key.created_at string|null

ISO timestamp for license key creation.

data.license_key.assigned_at string|null

ISO timestamp when checkout assigned the key.

data.payment.type string|null

Payment method type reported by Stripe.

data.payment.wallet string|null

Wallet type when a wallet was used.

data.payment.card_brand string|null

Card brand when available.

data.payment.card_funding string|null

Card funding type when available.

data.payment.card_country string|null

Card issuing country when available.

data.payment.card_last4 string|null

Last four digits of the card when available.

data.payment.receipt_url string|null

Stripe receipt URL when available.

data.completed_at string|null

ISO timestamp when checkout completed.

data.refunded_at string|null

ISO timestamp when the order was refunded.

data.created_at string|null

ISO timestamp for creation.

data.updated_at string|null

ISO timestamp for last update.

Discount code object

Discounts

Discount codes let you offer percentage or fixed-amount promotions in checkout. Codes can be globally usable, limited by total redemptions, restricted to a customer email, or restricted to one product.

  • Use discount endpoints to coordinate launch campaigns, affiliate codes, support coupons, and limited promotions from another system.
  • Product restrictions use product UUIDs, not internal database IDs.
GET /api/v1/discounts

List discounts

Audit active campaigns, sync coupons to support tools, or report on remaining redemption capacity.

Inputs
page query
Optional

Page number to fetch from the paginated collection. Defaults to 1.

per_page query
Optional

Number of records to return per page. Defaults to 25 and is capped at 100.

Returns
A paginated list of Discount Code objects.
Auth
Account API key
Response properties
data[] array

Array of Discount Code objects for the requested page.

links object

Pagination URLs for first, last, previous, and next pages.

meta object

Pagination metadata including current_page, per_page, total, and last_page.

data[].id string

Public discount UUID.

data[].code string

Normalized uppercase checkout code.

data[].discount_type string

Discount mode: percent or amount.

data[].percent_off integer|null

Percentage off when discount_type is percent.

data[].amount_off_cents integer|null

Fixed amount off in cents when discount_type is amount.

data[].max_redemptions integer|null

Maximum total uses, or null for unlimited.

data[].max_redemptions_per_customer integer|null

Maximum uses per customer email, or null for unlimited.

data[].redemptions_count integer

Number of completed redemptions.

data[].remaining_redemptions integer|null

Remaining uses based on max_redemptions.

data[].expires_at string|null

ISO expiration timestamp when set.

data[].is_active boolean

Whether the code can currently be redeemed.

data[].restricted_product.id string|null

Restricted product UUID when the code is product-scoped.

data[].restricted_product.title string|null

Restricted product title when loaded.

data[].restricted_customer_email string|null

Email restriction when set.

data[].created_at string|null

ISO timestamp for creation.

data[].updated_at string|null

ISO timestamp for last update.

GET /api/v1/discounts/{discount_id}

Retrieve a discount

Fetch one discount when you need to show campaign details, redemption counts, remaining usage, or product restrictions in another tool.

Inputs
discount_id path
Required

Discount UUID returned as id by the API.

Returns
A single Discount Code object.
Auth
Account API key
Response properties
data.id string

Public discount UUID.

data.code string

Normalized uppercase checkout code.

data.discount_type string

Discount mode: percent or amount.

data.percent_off integer|null

Percentage off when discount_type is percent.

data.amount_off_cents integer|null

Fixed amount off in cents when discount_type is amount.

data.max_redemptions integer|null

Maximum total uses, or null for unlimited.

data.max_redemptions_per_customer integer|null

Maximum uses per customer email, or null for unlimited.

data.redemptions_count integer

Number of completed redemptions.

data.remaining_redemptions integer|null

Remaining uses based on max_redemptions.

data.expires_at string|null

ISO expiration timestamp when set.

data.is_active boolean

Whether the code can currently be redeemed.

data.restricted_product.id string|null

Restricted product UUID when the code is product-scoped.

data.restricted_product.title string|null

Restricted product title when loaded.

data.restricted_customer_email string|null

Email restriction when set.

data.created_at string|null

ISO timestamp for creation.

data.updated_at string|null

ISO timestamp for last update.

PATCH /api/v1/discounts/{discount_id}

Update a discount

Pause a campaign, change redemption limits, extend an expiration date, or move a code to a different product restriction.

Inputs
discount_id path
Required

Discount UUID returned as id by the API.

code body
Optional

Discount code customers enter at checkout. Zwely normalizes it to uppercase letters and numbers.

discount_type body
Optional

Discount mode. Use percent for percentage discounts or amount for fixed-cent discounts.

percent_off body
Conditional

Percentage off from 1 to 100. Required when switching a code to percent.

amount_off_cents body
Conditional

Fixed discount amount in cents. Required when switching a code to amount.

max_redemptions body
Optional

Maximum total uses for the code. Leave null for no account-level cap.

max_redemptions_per_customer body
Optional

Maximum uses per customer email. Leave null for no per-customer cap.

expires_at body
Optional

Future expiration timestamp. Send null to clear the expiration on update.

is_active body
Optional

Boolean switch for whether the code can currently be used at checkout.

restricted_product_id body
Optional

Optional product UUID that limits the code to one product. Send null to remove the restriction.

restricted_customer_email body
Optional

Optional customer email that limits redemption to one buyer. Zwely normalizes email casing.

Returns
The updated Discount Code object.
Auth
Account API key
Response properties
data.id string

Public discount UUID.

data.code string

Normalized uppercase checkout code.

data.discount_type string

Discount mode: percent or amount.

data.percent_off integer|null

Percentage off when discount_type is percent.

data.amount_off_cents integer|null

Fixed amount off in cents when discount_type is amount.

data.max_redemptions integer|null

Maximum total uses, or null for unlimited.

data.max_redemptions_per_customer integer|null

Maximum uses per customer email, or null for unlimited.

data.redemptions_count integer

Number of completed redemptions.

data.remaining_redemptions integer|null

Remaining uses based on max_redemptions.

data.expires_at string|null

ISO expiration timestamp when set.

data.is_active boolean

Whether the code can currently be redeemed.

data.restricted_product.id string|null

Restricted product UUID when the code is product-scoped.

data.restricted_product.title string|null

Restricted product title when loaded.

data.restricted_customer_email string|null

Email restriction when set.

data.created_at string|null

ISO timestamp for creation.

data.updated_at string|null

ISO timestamp for last update.

message string

Confirmation message for the update action.

License validation result

License validation

License validation checks whether a license key belongs to a product and was assigned by a real checkout. Use it to unlock paid software, plugins, downloads, or subscription-adjacent product access.

  • Server-side validation uses an account API key and can return customer and order details for your backend.
  • Client-safe validation uses a product-scoped validation token and omits customer email, order financials, and other sensitive data.
  • A key is valid only when it belongs to the product, has been assigned by checkout, has a customer and order, and the order is not failed or refunded.
  • Status values are valid, not_found, unassigned, email_mismatch, refunded, and inactive_order.
POST /api/v1/license-validations

Validate a license server-side

Call this from your own server when you need the richest answer: whether the key is valid, which buyer owns it, and which order assigned it.

Inputs
product_id body
Required

Product UUID the license key must belong to.

license_key body
Required

License key string issued by Zwely after checkout assignment.

customer_email body
Optional

Optional buyer email check. When provided, Zwely returns email_mismatch if the key belongs to a different email.

Returns
A rich License Validation Result with product, license, customer, and order details.
Auth
Account API key
Response properties
data.valid boolean

True only when the key belongs to the product, is assigned, and the order is active.

data.status string

Validation status: valid, not_found, unassigned, email_mismatch, refunded, or inactive_order.

data.product.id string|null

Product UUID when the key can be associated with the token-scoped product.

data.product.title string|null

Product title when available.

data.license.created_at string|null

ISO timestamp when the license key was created.

data.license.assigned_at string|null

ISO timestamp when checkout assigned the key.

data.license.key string|null

Raw license key. Returned only by the server-side endpoint.

data.customer.id string|null

Customer UUID when a customer is attached to the key.

data.customer.email string|null

Customer email. Returned only by the server-side endpoint.

data.customer.name string|null

Customer name when available.

data.order.id string|null

Order UUID when a checkout assigned the key.

data.order.status string|null

Order status used for validity checks.

data.order.amount_cents integer|null

Order amount in cents. Returned only server-side.

data.order.currency string|null

Order currency.

data.order.completed_at string|null

ISO timestamp when the order completed.

POST /api/v1/public/license-validations

Validate a license from software

Call this from distributed software with a product-scoped validation token. The response is intentionally minimal so the app can unlock access without exposing private buyer or order data.

Inputs
license_key body
Required

License key string issued by Zwely after checkout assignment.

product_id body
Optional

Optional product UUID. If sent, it must match the product bound to the validation token.

customer_email body
Optional

Optional buyer email check. The public response still omits buyer PII.

Returns
A client-safe License Validation Result with valid status, product identity, and license timestamps.
Auth
Product-scoped validation token
Response properties
data.valid boolean

True only when the key belongs to the product, is assigned, and the order is active.

data.status string

Validation status: valid, not_found, unassigned, email_mismatch, refunded, or inactive_order.

data.product.id string|null

Product UUID when the key can be associated with the token-scoped product.

data.product.title string|null

Product title when available.

data.license.created_at string|null

ISO timestamp when the license key was created.

data.license.assigned_at string|null

ISO timestamp when checkout assigned the key.

Webhooks

Receive order events in your own app

Webhook endpoints let your backend react when a Zwely checkout creates an order. Zwely sends order.created for both free and paid orders, so you can update a CRM, grant access in another system, notify a team, or start your own onboarding flow without polling the Orders API.

  • Register webhook URLs from Account API Keys. Zwely posts JSON to each active endpoint after an order is created.
  • Each delivery includes Zwely-Event, Zwely-Delivery, and Zwely-Signature headers.
  • Bundle orders include delivery_items so your backend can see each included product, download availability, filename, and assigned license key.
  • The signature uses your endpoint signing secret. Build the signed payload as timestamp + "." + raw_request_body and verify the v1 HMAC SHA-256 value.
  • Return a 2xx response quickly. If your app needs more time, store the payload and process it asynchronously.