Filter
What would you like to search for?
Backend API
The Swell Backend API is organized around REST principles. It uses predictable resource-oriented URLs, standard HTTP verbs, and response codes. It also accepts and returns JSON-encoded request and response bodies.
Base URL
https://api.swell.store
Before using the API, you will need to create a Swell account.
Your account provides access to your store ID and API key which are necessary for API access. To get your API keys, navigate to the Developer section in the dashboard's left-hand nav and select API keys.
- Your store ID is located at the top of the API keys page.
- Click on the eye icon to reveal a Secret key in order to copy it.
You can add or revoke secret keys if the security of any key is compromised.
API authentication differs depending on which library is being used when accessing the API. Refer to the authentication example below when using any of the official API libraries.
While the HTTP protocol is supported, official libraries use a custom wire protocol that improves performance and caching. When using these libraries, your server must be able to connect to the API on port 8443. If you have trouble connecting, have a system administrator check your firewall settings.
Attributes
$ curl https://client_id:client_key@api.swell.store/products
Swell uses standard HTTP status codes to indicate the success or failure of an API request. A code in the range of 2xx indicates success, a code in the range of 4xx indicates there was a problem with the arguments provided (e.g., a required field was missing), and a code in the range of 5xx indicates an error occurred with Swell's servers.
A validation error object is returned when a request could not be fulfilled due to one or more invalid values.
Attributes
Fields
A distinct code indicating the cause of the error.
A human-readable description of the error.
Object containing parameter values related to the error.
Response
{
"errors": {
"name": {
"code": "REQUIRED",
"message": "Required"
},
"email": {
"code": "FORMAT_EMAIL",
"message": "Must be a valid email address"
}
}
}
Swell API libraries return a validation error object in case of an invalid PUT, POST, or DELETE request, and throw in any other error case.
There are several parameters you can use to effect the outcome of a query.
Query parameter reference for querying with Swell's Backend API.
Fields
An object containing criteria to filter results by.
A string expression used to sort results.
A number indicating the max number of results to return up to 1000.
A number indicating which page of results to return.
A string to search and filter results by.
A string or array of fields to expand in the result.
An object with additional queries to include as fields in the result.
Use the where parameter to filter results by their values. Swell offers native support for most MongoDB Query Operators including comparison operators like $gt and $lt—logical operators like $and and $or—and many others. You can combine many fields in one query.
$ curl https://api.swell.store/products?where[date_created][$gte]=2018-01-01T00:00:00Z&where[stock_level][$gt]=0&where[active]=true
-u store-id:secret-key
Use the sort parameter to sort results. The format consists of <field> <direction>. Direction is recognized as a case-insensitive word like ascending and descending, or as abbreviated asc and desc.
You can combine multiple sort fields in a string or array, with the first taking precedence in order.
$ curl https://api.swell.store/products?sort=name+asc
-u store-id:secret-key
Use the limit parameter to determine how many records should be returned in a result, up to 1000. Defaults to 15. Optionally use in combination with page to perform pagination.
$ curl https://api.swell.store/products?limit=100
-u store-id:secret-key
Use the page parameter to determine which page of results to return, relative to the default or specified limit. Defaults to 1.
$ curl https://api.swell.store/products?page=2
-u store-id:secret-key
Use the search parameter to perform a text search across all text fields in a given collection. This is a basic implementation that uses a combination of regular expressions, meaning it will match exact words only. For example, a search for "blue shirts" will match records containing both the words "blue" and "shirts". Searching is not case-sensitive.
When building product search for a complex store, we recommend Algolia.
$ curl https://api.swell.store/products?search=blue+shirts
-u store-id:secret-key
Expanding allows you to include related records as defined by link or collection fields. For example, in the cart model, items are linked to a product with the product field which means they aren't automatically included in the result when retrieving a cart. Since the item product is nested in a list of objects, you would use dot-notation to specify the path to the expandable field.
When the expandable field refers to many records, you may want to specify a limit to include more than the default limit, which is 5. To do that for example, use the format variants:50 with the field name and limit separated by :.
When retrieving a list of results, expand will be performed on all records in the result set.
$ curl https://api.swell.store/carts/5407e0929fe97f9d4c712a5e?expand=items.product,items.variant
-u store-id:secret-key
Response
{
"id": "5407e0929fe97f9d4c712a5e",
"items": [
{
"id": "5407e0929fe97f9d4c712a5f",
"product_id": "5407e0929fe97f9d4c712a5g",
"product": {
"name": "Example product",
...
}
},
{...}
],
...
}
Use the include parameter to include results in a query that may or may not be related to the records being retrieved. For example, when you know there's a need to retrieve two similar records at a time in order to reduce the number of API calls a page would need.
Use include.params to specify relative values to the records returned by the main query. The actual field values will be substituted by the API. Use include.data to specify literal values for filtering the included result.
$ curl https://api.swell.store/orders/5407e0929fe97f9d4c712a5f?include[fulfilled_giftcards][url]=/giftcards&include[fulfilled_giftcards][params][order_id]=id&include[fulfilled_giftcards][data][balance][$gt]=0
-u store-id:secret-key
Response
{
"id": "5407e0929fe97f9d4c712a5f",
"fulfilled_giftcards": [
{
"id": "5407e0929fe97f9d4c712a5g",
"balance": 25
},
{...}
],
...
}
Swell offers native support for the MongoDB Aggregation Pipeline; a framework for data aggregation allowing you to summarize data for reporting and other purposes.
Use the aggregate parameter to construct a pipeline according to this Mongo reference.
$ curl https://api.swell.store/orders?aggregate[0][$match][$and][0][date_created][$gte]=2018-01-01T00:00:00Z&aggregate[0][$match][$and][1][date_created][$lte]=2019-01-01T00:00:00Z&aggregate[1][$group][count][$sum]=1&aggregate[1][$group][sub_total][$sum]=sub_total&aggregate[1][$group][avg_total][$avg]=sub_total&aggregate[1][$group][day][$dayOfMonth]=date_created&aggregate[1][$group][month][$month]=date_created&aggregate[1][$group][year][$year]=date_created \
-u store-id:secret-key
Use webhooks to get notified about events that happen in your Swell account. Configuring a webhook involves setting up your own application to receive incoming HTTP calls that contain data describing the event.
To configure a webhook, visit your Swell dashboard and go to Settings > Webhooks. Specify the URL to your webhook handler and one or more events to receive.
Swell is an event-based architecture that allows you to configure webhooks on a variety of events that occur within each of our base data models. These events are easily referenced when creating webhooks from within the Swell dashboard under Developer > Webhooks. All configured webhooks are also available at /:webhooks.
To view webhooks that have fired within your store, see the /events:webhooks endpoint.
Fields
The unique identifier for the webhook.
Alias used to refer to the webhook configuration.
URL endpoint for the webhook.
Array of trigger events for the webhook.
Determines whether the webhook is enabled. Defaults to false.
Indicates whether the webhook was automatically disabled. This occurs seven days after the first failed attempt and no subsequent successes.
Determines whether the webhook retries disabled events.
Displays the number failed webhook attempts.
The date the webhook's first failed attempt.
The date of the last warning for a failed attempt.
The final attempt for a webhook after continuous failed attempts. Webhooks are disabled 7 days after the first failed attempt.
Schedule for specifying when a webhook is to be fired.
The hour for which to fire the webhook. Min 0, max 23.
The day of the month for which to fire the webhook. Min 1, max 31.
The month for which to fire the webhook. Min 1, max 12.
The month for which to fire the webhook. Min 0, max 6.
Date for which the webhook is scheduled to fire.
The webhook model
{
"url": "http://localhost:5000",
"enabled": false,
"alias": "webhook",
"description": null,
"events": [
"order.created",
"order.submitted",
"order.updated"
],
"api": "com",
"date_final_attempt": null,
"date_scheduled": null,
"date_created": "2021-09-27T16:30:11.837Z",
"date_updated": "2021-10-28T16:04:21.648Z",
"id": "6151f193ae97e82ccbf6f0a7"
}
When setting up webhooks for custom models, you will need to create them via the API referencing the events listed on the custom model. For webhooks that utilize Swell's standard models, we recommend configuration through the Swell dashboard under Developer tools > Webhooks—each standard model's events are easily referenced within the UI.
Arguments
URL endpoint for the webhook.
Array of trigger events for the webhook.
The unique identifier for the webhook.
Alias used to refer to the webhook configuration.
Determines whether the webhook is enabled. Defaults to false.
Indicates whether the webhook was automatically disabled. This occurs seven days after the first failed attempt and no subsequent successes.
Determines whether the webhook retries disabled events.
Displays the number failed webhook attempts.
The date the webhook's first failed attempt.
The date of the last warning for a failed attempt.
The final attempt for a webhook after continuous failed attempts. Webhooks are disabled 7 days after the first failed attempt.
Schedule for specifying when a webhook is to be fired.
The hour for which to fire the webhook. Min 0, max 23.
The day of the month for which to fire the webhook. Min 1, max 31.
The month for which to fire the webhook. Min 1, max 12.
The month for which to fire the webhook. Min 0, max 6.
Date for which the webhook is scheduled to fire.
$ curl https://api.swell.store/products:variants \
-u store-id:secret-key \
-d url=http://localhost:5000 \
-d events=order.created, order.submitted \
The webhook model
{
"url": "http://localhost:5000",
"enabled": false,
"alias": "webhook",
"description": null,
"events": [
"order.created",
"order.submitted",
"order.updated"
],
"api": "com",
"date_final_attempt": null,
"date_scheduled": null,
"date_created": "2021-09-27T16:30:11.837Z",
"date_updated": "2021-10-28T16:04:21.648Z",
"id": "6151f193ae97e82ccbf6f0a7"
}
Retrieve an existing webhook using the id that was returned during creation.
Arguments
The unique identifier for the webhook.
Alias used to refer to the webhook configuration.
URL endpoint for the webhook.
Array of trigger events for the webhook.
Determines whether the webhook is enabled. Defaults to false.
Indicates whether the webhook was automatically disabled. This occurs seven days after the first failed attempt and no subsequent successes.
Determines whether the webhook retries disabled events.
Displays the number failed webhook attempts.
The date the webhook's first failed attempt.
The date of the last warning for a failed attempt.
The final attempt for a webhook after continuous failed attempts. Webhooks are disabled 7 days after the first failed attempt.
Schedule for specifying when a webhook is to be fired.
The hour for which to fire the webhook. Min 0, max 23.
The day of the month for which to fire the webhook. Min 1, max 31.
The month for which to fire the webhook. Min 1, max 12.
The month for which to fire the webhook. Min 0, max 6.
Date for which the webhook is scheduled to fire.
$ curl https://api.swell.store/webhooks/{id} \
-u store-id:secret-key
The webhook model
{
"url": "http://localhost:5000",
"enabled": false,
"alias": "webhook",
"description": null,
"events": [
"order.created",
"order.submitted",
"order.updated"
],
"api": "com",
"date_final_attempt": null,
"date_scheduled": null,
"date_created": "2021-09-27T16:30:11.837Z",
"date_updated": "2021-10-28T16:04:21.648Z",
"id": "6151f193ae97e82ccbf6f0a7"
}
Update a webhook.
Arguments
The unique identifier for the webhook.
Alias used to refer to the webhook configuration.
URL endpoint for the webhook.
Array of trigger events for the webhook.
Determines whether the webhook is enabled. Defaults to false.
Determines whether the webhook retries disabled events.
Schedule for specifying when a webhook is to be fired.
The hour for which to fire the webhook. Min 0, max 23.
The day of the month for which to fire the webhook. Min 1, max 31.
The month for which to fire the webhook. Min 1, max 12.
The month for which to fire the webhook. Min 0, max 6.
Date for which the webhook is scheduled to fire.
$ curl https://api.swell.store/webhooks/{id} \
-u store-id:secret-key \
-d enabled=true \
-d date_scheduled=2022-04-20T16:20:69.000Z \
-X PUT
The webhook model
{
"url": "http://localhost:5000",
"enabled": false,
"alias": "webhook",
"description": null,
"events": [
"order.created",
"order.submitted",
"order.updated"
],
"api": "com",
"date_final_attempt": null,
"date_scheduled": null,
"date_created": "2021-09-27T16:30:11.837Z",
"date_updated": "2021-10-28T16:04:21.648Z",
"id": "6151f193ae97e82ccbf6f0a7"
}
Return a list of webhooks.
Arguments
Expand link fields and child collections by using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Returns only the specified fields in the result.
- For example fields=name,slug would return only the fields name and slug in the response.
Supports nested object and array fields using dot-notation.
- For example, items.product_id. The product id is always returned.
Include one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.
The page number of results to return given the specified or default limit.
A text search is performed using the search argument. Searchable fields are defined by the model.
- For example, search=red would return records containing the word "red" anywhere in the defined text fields.
See searching for more details.
Expression to sort results by using a format similar to a SQL sort statement.
- For example, sort=name asc would return records sorted by name ascending.
See sorting for more details.
An object with criteria to filter the result.
- For example, active=true would return records containing a field active with the value true.
It's also possible to use query operators, for example, $eq, $ne, $gt, and more.
See querying for more details.
$ curl https://api.swell.store/webhooks?where[active]=true&limit=25&page=1 \
-u store-id:secret-key \
-G
The webhook model
{
"url": "http://localhost:5000",
"enabled": false,
"alias": "webhook",
"description": null,
"events": [
"order.created",
"order.submitted",
"order.updated"
],
"api": "com",
"date_final_attempt": null,
"date_scheduled": null,
"date_created": "2021-09-27T16:30:11.837Z",
"date_updated": "2021-10-28T16:04:21.648Z",
"id": "6151f193ae97e82ccbf6f0a7"
}
Delete a webhook.
Arguments
The id of the webhook to delete.
$ curl https://api.swell.store/webhooks/662ba123becf7601325cefa3 \
-u store-id:secret-key \
-X DELETE
The webhook model
{
"url": "http://localhost:5000",
"enabled": false,
"alias": "webhook",
"description": null,
"events": [
"order.created",
"order.submitted",
"order.updated"
],
"api": "com",
"date_final_attempt": null,
"date_scheduled": null,
"date_created": "2021-09-27T16:30:11.837Z",
"date_updated": "2021-10-28T16:04:21.648Z",
"id": "6151f193ae97e82ccbf6f0a7"
}
You may use an HTTPS URL for your webhook endpoint. In that case, Swell will validate your SSL certificate before sending event data. Your server must be correctly configured to support HTTPS.
Webhook event data is sent as JSON in a POST body. The payload represents a single event with attributes based on the event type. Events may contain additional data attributes that are useful in processing the event.
Your webhook might need to fetch the associated record using data.id before performing a relevant action.
Response
{
"id": "58991ed385c95b9e2e0aa433",
"date_created": "2019-02-07T01:11:47.219Z",
"model": "subscriptions",
"type": "subscription.paid",
"data": {
"id": "58991ed285c95b9e2e0aa42c",
"payment_id": "5ca3806f0e41a74b7138d085"
}
}
Your endpoint must respond to successful requests with a 2xx HTTP status code. All other information returned by your script will be ignored. Response codes outside this range will indicate that you were not able to receive the webhook event.
If a webhook is not acknowledged successfully, Swell will continue trying to send it once every hour for up to two days. After this time, we'll send an email alert and continue attempting to deliver the webhook every hour. If your endpoint does not respond after seven days, you will be notified finally and the webhook will be disabled until further action is taken.
Content localization is supported by providing alternative values for each configured locale. Any string or array of strings can be set in multiple locales with the $locale parameter when creating or updating objects.
Locales can be specified with or without a country code (e.g., en and en-US).
Use the format $locale: { <code>: { <field>: value } } with any PUT or POST request. For nested values, the $locale parameter must be defined on the nearest parent object.
All locale content is optional using this API, even if the setting Require content for this locale is enabled in the Swell dashboard.
$ curl https://api.swell.store/products/5cad15bc9b14d1990724663a \
-u store-id:secret-key \
-d name="Test product" \
-d $locale[fr][name]="Test produit" \
-d $locale[fr][tags]="étiqueter1, étiqueter2" \
-d $locale[es][name]="Producto de prueba" \
-d $locale[es][tags]="etiqueta1, etiqueta2" \
-X PUT
Use the query parameter $locale: <code>, or alternatively an HTTP header X-Locale: <code> with any GET request. All fields with localized values will be returned according to the locale code and fallback settings.
$ curl https://api.swell.store/products?$locale=es \
-u store-id:secret-key
Response
{
"count": 36,
"results": [
{
"id": "5cad15bc9b14d1990724663a",
"name": "Test produit",
"tags": ["étiqueter1", "étiqueter2"],
...
}
],
"page": 1,
...
}
To retrieve records with $locale values in order to review localized content or build custom localization interfaces, pass an array of locale codes using the parameter $locale: [<code>, ...] with any GET request. All objects with $locale values will be returned matching the specific locale codes requested.
$ curl https://api.swell.store/products?$locale=en,fr,es \
-u store-id:secret-key
Response
{
"count": 36,
"results": [
{
"id": "5cad15bc9b14d1990724663a",
"name": "Test product",
"$locale": {
"en": {
"name": "Test product",
"tags": ["tag1", "tag2"]
},
"fr": {
"name": "Test produit",
"tags": ["étiqueter1", "étiqueter2"]
},
"es": {
"name": "Producto de prueba",
"tags": ["etiqueta1", "etiqueta2"]
},
}
...
}
],
"page": 1,
...
}
The pages model contains data relating to pages within your storefront and the content within them.
We recommend not making changes via the API for the pages model when possible and suggest using the dashboard model editor instead. If you do wish to make changes via the API, see our data model customization guide.
Fields
Unique identifier for the page.
Human-friendly name of the page.
Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.
HTML formatted page content.
Date and time the page was created.
Date and time the page was published.
Date and time the page was updated.
Page description used for search engine optimization purposes.
Indicates whether the page is published. Defaults to false.
URL to specify a page redirect.
The pages model
{
"id": "5f5efea5703b7a10d8000007",
"name": "About Us",
"slug": "about-us",
"content": "Welcome to <strong>Strongbad's Awesome Store</strong>. We make awesome things for awesome people.",
"date_updated": "2021-09-16T01:05:27.003Z",
"date_published": "2020-09-28T09:08:23.005Z",
"date_created": "2020-09-28T09:07:17.091Z",
"meta_description": null,
"redirect": null,
"published": true,
}
Products represent items that can be sold to a customer, either as one-off sales or as subscriptions. For more complex subscription products and when physical items are involved, it's recommended to create a plan.
Fields
Unique identifier for the product.
Human-friendly name of the product.
Indicates whether the product is active and available in the storefront.
Configuration of one or more purchase options for the product. Can be standard for one-time purchases or subscription for a subscription plan. Products can support both purchase options simultaneously.
Designates purchase option as a one-time purchase.
ID of the purchase option.
The name of the purchase option.
A long-form description of the product. May contain HTML or other markup languages.
Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
List price used when sale=false or sale_price is not defined.
Indicates whether the product option is on sale. If true, the sale_price will be used by default when the product is added to a cart.
Sale price used by default when sale=true, overriding price. Overrides product sale price.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Array of account groups that are eligible to access the purchase option within the storefront.
Designates purchase option for a subscription plan.
ID of the subscription plan purchase option.
Name of the subscription plan purchase option.
A long-form description of the purchase option. May contain HTML or other markup languages.
Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
Array of account_group names for which the purchase option is available.
Array defining subscription plans and their respective configurations.
ID of the purchase option subscription plan.
Name of the subscription plan.
A long-form description of the subscription plan. May contain HTML or other markup languages.
Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
List price used when sale=false or sale_price is not defined.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Determines the billing schedule for the subscription plan.
Subscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
Specifies a limit to the number of billing cycles for the subscription plan. For example, limit=10 would stop billing the customer after the tenth billing cycle.
An object containing custom attribute key/value pairs.
Indicates whether the product is a bundle of other products.
List of products sold as a bundle. Applicable only when bundle=true.
Unique identifier for the bundle item.
ID of the bundled product.
Expandable link to the bundled product.
Quantity of the bundled product. Defaults to 1.
ID of the bundled variant, if applicable.
Expandable link to the bundled product variant, if applicable.
Expandable link to the primary category.
Primary category, commonly used as a navigation anchor.
Expandable link to all related product categories.
Index of categories used for fast lookup operations.
List of related product category IDs.
Index of category IDs and their respective sort positions.
Unique code to identify the gift card product.
Cost of goods (COGS) used to calculate gross margins.
List of products to display as cross-sells on a shopping cart page.
Unique identifier for the cross-sell object.
ID of the cross-sell product.
Expandable link to the cross-sell product.
Type of discount to apply, either fixed or percent.
Discount to apply as a fixed amount. Applicable only when discount_type=fixed.
Discount to apply as a percentage. Applicable only when discount_type=percent.
Three-letter ISO currency code in uppercase. Defaults to your store's base currency.
Indicates whether the product has custom options enabled.
Date and time the product was created.
Date and time the product was last updated.
Method of fulfillment automatically assigned based on type:
- shipment means the product will be physically shipped to a customer.
- subscription means the product will be fulfilled as a subscription when an order is placed. giftcard delivery means the product will be fulfilled as a gift card when an order is placed.
- null means the product will not be fulfilled by one of the above methods.
Note: A bundle has its child products fulfilled individually; each product in the bundle must have its own fulfillment method.
A long-form description of the product. May contain HTML or other markup languages.
Indicates whether the product has been discontinued.
List of images depicting the bundle.
Unique identifier for the image.
A brief description of the image, intended for display as a caption or alt text.
An object representing the image's source file.
Unique identifier for the file.
Optional file name.
A reference to the raw file data.
MIME content type of the file.
Date the file was uploaded.
Image height in pixels, if applicable.
Size of the file in bytes.
A set of arbitrary data that is typically used to store custom values.
An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
Indicates whether the file is private.
A public URL to reference the file. Updated automatically if file content changes.
Image width in pixels, if applicable.
Page title used to override product name in storefronts.
Page keywords used for search engine optimization purposes.
Page description used for search engine optimization purposes.
Options that allow for variations of the base product. If the option is part of a variant or required=true, an option value must be set for the product to be added to a cart.
Unique identifier for the object.
Human-friendly name of the option.
Some brief hint text to help the user understand this option.
Type of user input to display for this option in a storefront. Can be text, textarea, select, multi_select, file, or multi_file. select is ideal for dropdown or radio selectors, and multi_select is ideal for checkboxes. A maximum of 10 files can be uploaded by the user, and there are no restrictions on file type.
Specifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
IDs of parent option values that will make the option appear if selected.
Extra price for the option, added to the product's price/sale_price. If the option is part of a variant, the variant's price/sale_price will override this value.
Indicates whether the option requires a value when the product is added to a cart.
Indicates whether the option specifies the billing interval of a subscription plan.
List of possible values for this option.
Unique identifier for the object.
Human-friendly name of the option value.
Name of the product color.
A brief description of the option value, intended for displaying to customers.
Extra price added to the product's price/sale_price if the option value is selected. Overrides option price.
Extra weight added to the product's shipment_weight if the option value is selected. The unit should match the store's default as configured in general settings.
When product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly, or daily.
When product type=subscription, this number multiplies subscription_interval to determine the billing frequency when this option is selected. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
When product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
Image depicting the product.
Unique identifier for the object.
A reference to the raw file data.
Date the file was uploaded.
Size of the file in bytes.
An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
Optional file name.
MIME content type of the file.
Arbitrary data
Unique identifier for the attribute.
Description for the product options.
Indicates the options are active.
Indicates there are multiple selections for options.
Indicates the option is a variant.
List price used when sale=false or sale_price is not defined.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Minimum quantity of the product that can be sold at once.
Specifies a quantify multiple the product must be sold in.
Array of related product IDs.
Indicates whether the product is on sale. If true, the sale_price will be used by default when the product is added to a cart.
Sale price used to override list price when sale=true.
Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.
Length of the product in unit.
Width of the product in unit.
Height of the product in unit.
Either in(inches) or cm(centimeters).
ID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
Product shipping price rules to override default shipping rules.
Shipping service required for this rule to apply.
Customer group required for this rule to apply.
Shipping country required for this rule to apply.
Fixed amount to add when rule is applied. Only applicable when fee_type=fixed.
Percentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
Type of fee to apply in addition to price, either fixed or percent.
Maximum package quantity when rule is applied.
Shipping price when rule is applied.
Shipping state required for this rule to apply.
Maximum order subtotal for this rule to apply.
Minimum order subtotal for this rule to apply.
Maximum order item weight for this rule to apply.
Minimum order item weight for this rule to apply.
Shipping zip/postal code required for this rule to apply.
If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.
The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
Multiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
Stock keeping unit (SKU) used to track inventory in a warehouse.
Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.
Expandable list of stock adjustments for the product.
Indicates whether the product can be backordered if out of stock.
Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.
Indicates whether the product can be purchased as a preorder.
Indicates whether the product's stock is purchasable.
String indicating the product's stock status for the purpose of ordering. When stock_purchasable=true, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is available, preorder, or backorder.
Indicates whether the product has stock tracking enabled.
Array of searchable tags to aid in search discoverability.
Indicates the tax class for the product.
Product tax code for tracking with Avalara, TaxJar, etc.
Implies the ordering and fulfillment options available for the product. Can be standard, subscription, bundle, or giftcard. A standard product is a physical item that will be shipped to a customer.
List of products to display as up-sells on a product detail page.
Unique identifier for the up-sell.
ID of the up-sell product.
Expandable link to the up-sell product.
Indicates whether the product has variant generation enabled.
Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
Indicates whether the product is virtual.
The product model
{
"name": "Iron dagger",
"sku": "00090616",
"active": true,
"purchase_options": {
"standard": {
"active": true,
"price": 10,
"sale_price": null,
"sale": false,
"prices": []
},
"subscription": {
"active": true,
"plans": [
{
"name": "Monthly",
"description": "1 dagger/month",
"price": 9,
"billing_schedule": {
"interval": "monthly",
"interval_count": 1,
"limit": null,
"trial_days": 14
},
"id": "627c6f180d375a001296b593",
"active": true
}
]
}
},
"variable": true,
"description": "<h3>Damage: 7</h3><h3>Weight: 8</h3><h3>Health: 98</h3><h3>Speed: 1.4</h3><h3>Reach: 0.6</h3>",
"tags": [],
"meta_title": null,
"meta_description": null,
"slug": "iron-dagger",
"attributes": {
"blade": "",
"dagger": "",
"type": [
"Fine",
"Rusty"
]
},
"delivery": "shipment",
"bundle": null,
"price": 10,
"stock_tracking": false,
"options": [
{
"id": "627c6e36e80393798c171670",
"values": [
{
"id": "627c6f18e80393798c171673",
"name": "Fine",
"price": null,
"shipment_weight": null,
"description": "A better-than-usual iron dagger"
},
{
"id": "627c6f18e80393798c171674",
"name": "Rusty",
"price": 0,
"shipment_weight": null,
"description": "This dagger's seen better days"
}
],
"name": "Type",
"active": true,
"input_type": "select",
"variant": true,
"description": null,
"required": true,
"attribute_id": "type"
}
],
"currency": "USD",
"sale": false,
"sale_price": null,
"prices": [],
"type": "standard",
"tax_class": "standard",
"date_created": "2022-05-12T02:21:12.534Z",
"stock_status": null,
"date_updated": "2022-05-12T02:37:45.666Z",
"category_index": {
"sort": {
"627c6db5632818001272f8ed": 0,
"627c6dc30d375a001296a8b7": 0
},
"id": [
"627c6db5632818001272f8ed",
"627c6dc30d375a001296a8b7"
]
},
"cross_sells": [],
"up_sells": [
{
"id": "627c7225e80393798c17167b",
"product_id": "627c715e632818001274ebd8"
}
],
"id": "627c6f180d375a001296b580"
Create a new product.
Arguments
Human-friendly name of the product.
An object containing custom attribute key/value pairs. See attributes for more details.
List price used when sale=false or sale_price is not defined.
Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.
Configuration of one or more purchase options for the product. Can be standard for one-time purchases or subscription for a subscription plan. Products can support both purchase options simultaneously.
Designates purchase option as a one-time purchase.
ID of the purchase option.
The name of the purchase option.
A long-form description of the product. May contain HTML or other markup languages.
Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
List price used when sale=false or sale_price is not defined.
Indicates whether the product option is on sale. If true, the sale_price will be used by default when the product is added to a cart.
Sale price used by default when sale=true, overriding price. Overrides product sale price.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Array of account groups that are eligible to access the purchase option within the storefront.
Designates purchase option as a subscription plan.
ID of the subscription plan purchase option.
Name of the subscription plan purchase option.
A long-form description of the purchase option. May contain HTML or other markup languages.
Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
Array of account_group names for which the purchase option is available.
Array defining subscription plans and their respective configurations.
ID of the purchase option subscription plan.
Name of the subscription plan.
A long-form description of the subscription plan. May contain HTML or other markup languages.
Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
List price used when sale=false or sale_price is not defined.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Determines the billing schedule for the subscription plan.
Subscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
Specifies a limit to the number of billing cycles for the subscription plan. For example, limit=10 would stop billing the customer after the tenth billing cycle.
Method of fulfillment automatically assigned based on type:
- shipment means the product will be physically shipped to a customer.
- subscription means the product will be fulfilled as a subscription when an order is placed. giftcard delivery means the product will be fulfilled as a gift card when an order is placed.
- null means the product will not be fulfilled by one of the above methods.
Note: A bundle has its child products fulfilled individually; each product in the bundle must have its own fulfillment method.
Set true to make the product visible to customers in a storefront, otherwise it will be hidden.
Indicates whether the product is a bundle of other products.
List of products sold as a bundle. Applicable only when bundle=true.
ID of the bundled product.
ID of the bundled product.
Expandable link to the bundled product.
Quantity of the bundled product. Defaults to 1.
ID of the bundled variant, if applicable.
Expandable link to the bundled product variant, if applicable.
Primary category, commonly used as a navigation anchor.
Cost of goods (COGS) that is used to calculate gross margins.
List of products to display as cross-sells on a shopping cart page.
Unique identifier for the cross-sell object.
ID of the cross-sell product.
Expandable link to the cross-sell product.
Discount to apply as a fixed amount. Applicable only when discount_type=fixed.
Discount to apply as a percentage. Applicable only when discount_type=percent.
Type of discount to apply, either fixed or percent.
Set true to enable custom options for this product in the admin panel.
A long form description of the product. May have HTML or other markup.
List of images depicting the bundle.
Unique identifier for the image.
A brief description of the image, intended for display as a caption or alt text.
An object representing the image's source file.
Optional file name.
Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.
Page description used for search engine optimization purposes.
Page keywords used for search engine optimization purposes.
Page title used to override product name in storefronts.
Set price rules to use when conditions match the customer's account group or product quantity in a cart.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Specifies a quantified multiple the product must be sold in.
Minimum quantity of the product that can be sold at once.
Set true to mark the product "on sale" and to use sale_price when the product is added to a cart.
Sale price used to override list price when sale=true.
Product dimensions when packed for shipping. Typically used by 3rd party carriers in box packing algorithms to optimize shipping costs.
Height of the product in unit.
Length of the product in unit.
Either in (inches) or cm (centimeters).
Width of the product in unit.
ID of location from /settings/shipping/locations. If specified, shipping is calculated from this origin. Otherwise, the store's default location will be used.
Product shipping price rules to override default shipping rules.
Shipping service required for this rule to apply.
Maximum package quantity when rule is applied.
Shipping price when rule is applied.
Type of fee to apply in addition to price, either fixed or percent.
Fixed amount to add when rule is applied. Only applicable when fee_type=fixed.
Percentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
Minimum order subtotal for this rule to apply.
Maximum order subtotal for this rule to apply.
Minimum order item weight for this rule to apply.
Maximum order item weight for this rule to apply.
Shipping state required for this rule to apply.
Shipping zip/postal code required for this rule to apply.
Shipping country required for this rule to apply.
Customer group required for this rule to apply.
If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg — depending on store's default weight unit.
Stock keeping unit (SKU) used to track inventory in a warehouse.
Set true to enable stock tracking this product.
The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
Multiplier when combined with subscription_interval. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2.
Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
List of products to display as up-sells on a product detail page.
Unique identifier for the up-sell.
ID of the up-sell product.
Expandable link to the up-sell product.
Set true to generate variants for this product in the admin panel.
Expandable link to the primary category.
Expandable link to all related product categories.
Index of categories used for fast lookup operations.
Index of category IDs and their respective sort positions.
Expandable list of stock adjustments for the product.
Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.
String indicating the product's stock status for the purpose of ordering. When stock_purchasable=true, an order can be placed for this product regardless of current stock status, otherwise an order submission will be blocked unless stock status is available, preorder ,or backorder.
Three-letter ISO currency code in uppercase. Defaults to your store's base currency.
$ curl https://api.swell.store/products \
-u store-id:secret-key \
-d name="T-Shirt" \
-d price=99 \
-d active=true \
-d options[0][name]=Size \
-d options[0][values][0][name]=Small \
-d options[0][values][1][name]=Large
Response
{
"id": "5ca24abb9c077817e5fe2b36",
"active": true,
"attributes": {},
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"delivery": "shipment",
"name": "T-Shirt",
"options": [
{
"id": "5ca24ab32599d4179c24a624",
"name": "Size",
"variant": true,
"required": true,
"values": [
{
"id": "5ca24ad59c077817e5fe2ba3",
"name": "Small"
},
{
"id": "5ca24ad59c077817e5fe2ba4",
"name": "Medium"
},
{
"id": "5ca24ad59c077817e5fe2ba5",
"name": "Large"
}
]
}
],
"price": 99.00,
"slug": "swell-t-shirt",
"type": "standard"
}
Retrieve an existing product using the ID that was returned when created.
Arguments
The id of the product to retrieve.
Expanding link fields and child collections is performed using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Return only the specified fields in the result. For example fields=name,slug would return only the fields name and slug in the response. Supports nested object and array fields using dot-notation.
- For example, items.product_id. The category id is always returned.
Include one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
$ curl https://api.swell.store/products/5c8fb5e1ed2faf8c79da492a \
-u store-id:secret-key
Response
{
"id": "5ca24abb9c077817e5fe2b36",
"active": true,
"attributes": {},
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"date_updated": "2019-04-02T00:26:23.399Z",
"delivery": "shipment",
"description": null,
"images": [
{
"id": "5ca24abb9c077817e5fe2b37",
"file": {
"id": "5ca24abb9c077817e5fe2b38",
"date_uploaded": "2019-04-02T00:26:23.399Z",
"length": 66764,
"md5": "99194f53bfdea832553e7fa8ae8fd80f",
"content_type": "image/png",
"url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
"width": 940,
"height": 600
}
}
],
"meta_description": null,
"meta_title": null,
"name": "T-Shirt",
"options": [
{
"id": "5ca24ab32599d4179c24a624",
"name": "Size",
"variant": true,
"required": true,
"values": [
{
"id": "5ca24ad59c077817e5fe2ba3",
"name": "Small"
},
{
"id": "5ca24ad59c077817e5fe2ba4",
"name": "Medium"
},
{
"id": "5ca24ad59c077817e5fe2ba5",
"name": "Large"
}
]
}
],
"price": 9.99,
"slug": "swell-t-shirt",
"stock_level": 0,
"stock_status": "available",
"stock_tracking": true,
"tags": [],
"type": "standard"
}
Updates an existing product using the ID that was returned when created. Updating performs a merge operation. To explicitly override values such as arrays, use the $set operator.
Arguments
Unique identifier for the product.
Set true to make the product visible to customers in a storefront, otherwise it will be hidden.
An object containing custom attribute key/value pairs. See attributes for more details.
Human-friendly name of the product.
List price used when sale=false or sale_price is not defined.
Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.
Configuration of one or more purchase options for the product. Can be standard for one-time purchases or subscription for a subscription plan. Products can support both purchase options simultaneously.
Designates purchase option as a one-time purchase.
ID of the purchase option.
The name of the purchase option.
Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
Whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
List price used when sale=false or sale_price is not defined.
Indicates whether the product option is on sale. If true, the sale_price will be used by default when the product is added to a cart.
Sale price used by default when sale=true, overriding price. Overrides product sale price.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Array of account groups that are eligible to access the purchase option within the storefront.
Designates purchase option as a subscription plan.
ID of the subscription plan purchase option.
Name of the subscription plan purchase option.
A long-form description of the purchase option. May contain HTML or other markup languages.
Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
Array of account_group names for which the purchase option is available.
Array defining subscription plans and their respective configurations.
ID of the purchase option subscription plan.
Name of the subscription plan.
A long-form description of the subscription plan. May contain HTML or other markup languages.
Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
List price used when sale=false or sale_price is not defined.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Determines the billing schedule for the subscription plan.
Subscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
Specifies a limit to the number of billing cycles for the subscription plan. For example, "limit"=10 would stop billing the customer after the tenth billing cycle.
Indicates whether the product is a bundle of other products.
List of products sold as a bundle. Applicable only when bundle=true.
The id of the bundled product.
Quantity of the bundled product.
The id of the bundled variant, if applicable.
Primary category, commonly used as a navigation anchor.
Cost of goods (COGS) used to calculate gross margins.
List of products to display as cross-sells on a shopping cart page.
The id of the cross-sell product.
Discount to apply as a fixed amount. Applicable only when discount_type=fixed
Discount to apply as a percentage. Applicable only when discount_type=percent.
Type of discount to apply: fixed or percent.
Set true to enable custom options for this product in the admin panel.
A long form description of the product. May have HTML or other markup.
List of images depicting the bundle.
A brief description of the image, intended for display as a caption or alt text.
An object representing the image's source file.
Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.
Optional file name.
Page description used for search engine optimization purposes.
Page keywords used for search engine optimization purposes.
Page title used to override product name in storefronts.
Options that allow for variations of the base product. If the option is part of a variant or required=true, an option value must be set for the product to be added to a cart.
Human-friendly name of the option.
Some brief hint text to help the user understand this option.
Type of user input to display for this option in a storefront. Can be text, textarea, select, multi_select, file or multi_file. select is ideal for dropdown or radio selectors, and multi_select is ideal for checkboxes. A maximum of 10 files can be uploaded by the user, and there are no restrictions on file type.
Specifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
The ids of parent option values that will make the option appear if selected.
Extra price for the option, added to the product's price/sale_price. If the option is part of a variant, the variant's price/sale_price will override this value.
Set true to indicate the option's values specify a subscription billing interval. In this case, option values must have a subscription_interval of monthly, yearly, weekly or daily.
List of possible values for this option.
Human-friendly name of the option value.
A brief description of the option value, intended for displaying to customers.
One or more images depicting the option value.
A brief description of the image, intended for display as a caption or alt text.
An object representing the image's source file.
Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.
Optional file name.
Extra price added to the product's price/sale_price if the option value is selected. Overrides option price.
Extra weight added to the product's shipment_weight if the option value is selected. The unit should match the store's default as configured in general settings.
When product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly or daily.
When product type=subscription, this number multiplies subscription_interval to determine the billing frequency when this option is selected. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2.
When product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
Set true to generate variants including this option.
Set price rules to use when conditions match the customer's account group or product quantity in a cart.
Set price to apply when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Specifies a quantity multiple the product must be sold in.
Minimum quantity of the product that can be sold at once.
Set true to mark the product "on sale" and to use sale_price when the product is added to a cart.
Sale price used to override list price when sale=true.
Product dimensions when packed for shipping. Typically used by 3rd party carriers in box packing algorithms to optimize shipping costs.
Height of the product in unit.
Length of the product in unit.
Either in (inches) or cm (centimeters).
Width of the product in unit.
ID of location from /settings/shipping/locations. If specified, shipping is calculated from this origin. Otherwise, the store default location will be used.
If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
Product shipping price rules to override default shipping rules.
Shipping service required for this rule to apply.
Customer group required for this rule to apply.
Shipping country required for this rule to apply.
Fixed amount to add when rule is applied. Only applicable when fee_type=fixed.
Percentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
Type of fee to apply in addition to price, either fixed or percent.
Maximum package quantity when rule is applied.
Shipping price when rule is applied.
Shipping state required for this rule to apply.
Maximum order subtotal for this rule to apply.
Minimum order subtotal for this rule to apply.
Maximum order item weight for this rule to apply.
Minimum order item weight for this rule to apply.
Shipping zip/postal code required for this rule to apply.
If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg — depending on store's default weight unit.
Stock keeping unit (SKU) used to track inventory in a warehouse.
Set true to enable stock tracking this product.
The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly or daily.
Multiplier when combined with subscription_interval. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2.
Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
List of arbitrary tags typically used as metadata to improve search results or associate custom behavior with a product.
Implies the ordering and fulfillment options available for the product. Can be standard, subscription, bundle, or giftcard. A standard product is a physical item that will be shipped to a customer.
List of products to display as up-sells on a product detail page.
The id of the up-sell product.
Set true to generate variants for this product in the admin panel.
$ curl https://api.swell.store/products/5c8fb5e1ed2faf8c79da492a \
-u store-id:secret-key \
-d price=9.99 \
-X PUT
Response
{
"id": "5ca24abb9c077817e5fe2b36",
"active": true,
"attributes": {},
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"date_updated": "2019-04-01T00:00:00.000Z",
"delivery": "shipment",
"description": null,
"images": [
{
"id": "5ca24abb9c077817e5fe2b37",
"file": {
"id": "5ca24abb9c077817e5fe2b38",
"date_uploaded": "2019-04-02T00:26:23.399Z",
"length": 66764,
"md5": "99194f53bfdea832553e7fa8ae8fd80f",
"content_type": "image/png",
"url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
"width": 940,
"height": 600
}
}
],
"meta_description": null,
"meta_title": null,
"name": "T-Shirt",
"options": [
{
"id": "5ca24ab32599d4179c24a624",
"name": "Size",
"variant": true,
"required": true,
"values": [
{
"id": "5ca24ad59c077817e5fe2ba3",
"name": "Small"
},
{
"id": "5ca24ad59c077817e5fe2ba4",
"name": "Medium"
},
{
"id": "5ca24ad59c077817e5fe2ba5",
"name": "Large"
}
]
}
],
"price": 9.99,
"slug": "swell-t-shirt",
"stock_level": 0,
"stock_status": "available",
"stock_tracking": true,
"tags": [],
"type": "standard"
}
Return a list of products.
Arguments
Expand link fields and child collections by using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Returns only the specified fields in the result.
- For example fields=name,slug would return only the fields name and slug in the response.
Supports nested object and array fields using dot-notation.
- For example, items.product_id. The product id is always returned.
Include one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.
The page number of results to return given the specified or default limit.
A text search is performed using the search argument. Searchable fields are defined by the model.
- For example, search=red would return records containing the word "red" anywhere in the defined text fields.
See searching for more details.
Expression to sort results by using a format similar to a SQL sort statement.
- For example, sort=name asc would return records sorted by name ascending.
See sorting for more details.
An object with criteria to filter the result.
- For example, active=true would return records containing a field active with the value true.
It's also possible to use query operators, for example, $eq, $ne, $gt, and more.
See querying for more details.
$ curl https://api.swell.store/products?where[active]=true&limit=25&page=1 \
-u store-id:secret-key \
-G
Response
{
"count": 51,
"results": [
{
"id": "5ca24abb9c077817e5fe2b36",
"active": true,
"attributes": {},
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"date_updated": "2019-04-01T00:00:00.000Z",
"delivery": "shipment",
"description": null,
"images": [],
"meta_description": null,
"meta_title": null,
"name": "T-Shirt",
"options": [],
"price": 9.99,
"slug": "swell-t-shirt",
"stock_level": 0,
"stock_status": "available",
"stock_tracking": true,
"tags": [],
"type": "standard"
},
{...},
{...}
],
"page": 1,
"pages": {
"1": {
"start": 1,
"end": 25
},
"2": {
"start": 26,
"end": 50
},
"2": {
"start": 51,
"end": 51
}
}
}
Deleting a product that has already been sold will break any links that exist within orders. We recommend only deleting products that have not yet been sold to a customer.
When deleting a record that has child collections such as variants and stock, the contents of those collections are also deleted.
Arguments
The id of the product you wish to delete.
$ curl https://api.swell.store/products/5c8fb5e1ed2faf8c79da492a \
-u store-id:secret-key \
-X DELETE
Response
{
"id": "5ca24abb9c077817e5fe2b36",
"active": true,
"attributes": {},
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"date_updated": "2019-04-01T00:00:00.000Z",
"delivery": "shipment",
"description": null,
"images": [],
"meta_description": null,
"meta_title": null,
"name": "T-Shirt",
"options": [],
"price": 9.99,
"slug": "swell-t-shirt",
"stock_level": 0,
"stock_status": "available",
"stock_tracking": true,
"tags": [],
"type": "standard"
}
Fields
Unique identifier for the variant.
Human-friendly name of the variant. Defaults to the combined name of all options, for example "Blue, Large" in the case of 2 options; color and size.
The id of the parent product.
An active variant is visible to customers in a storefront. Otherwise it will be hidden from view.
A variant is automatically archived when it has been sold in the past and product options are changed in a way that would cause the variant to be removed.
An object containing custom attribute values. Overrides product attributes. See attributes for more details.
Unique code to identify the gift card variant.
Cost of goods used to calculate gross margins. Overrides parent product cost.
Three-letter ISO currency code in uppercase. Defaults to store's base currency.
Date and time the variant was created.
Date and time the variant was last updated.
List of images depicting the variant.
Unique identifier for the object.
A brief description of the image.
An object representing the image file.
Unique identifier for the file.
MIME content type of the file.
A reference to the raw file data.
Date the file was uploaded.
Optional file name.
Image height in pixels, if applicable.
Size of the file in bytes.
An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
A public URL to reference the file. Updated automatically if file content changes.
Image width in pixels, if applicable.
List of option value IDs that constitute the variant.
Expandable link to the parent product.
List price used by default when sale=false or sale_price is not defined. Overrides parent product price.
Price rules to override price and sale_price when conditions match quantity or account group in a cart. Overrides parent product prices.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Purchase options available for the product variant.
Designates purchase option as a one-time purchase.
List price used by default when sale=false or sale_price is not defined. Overrides product price.
Indicates whether the product option is on sale. If true, the sale_price will be used by default when the product is added to a cart.
Sale price used by default when sale=true, overriding price. Overrides product sale price.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Indicates the variant is on sale andsale_price is used by default when the product is added to a cart. Overrides parent product sale.
Sale price used by default when sale=true, overriding price. Overrides parent product sale_price.
If specified, shipping is calculated based on this shipping weight. Otherwise, it will assume 1 lb/oz/kg depending on your default weight unit. Overrides parent product shipment_weight.
Stock keeping unit (SKU) used to track inventory in a warehouse.
Expandable list of stock adjustments for the variant.
Current in-stock quantity of the variant, based on the sum of stock entries.
The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly or daily.
Multiplier when combined with subscription_interval. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2.
Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
The product variant model
{
"id": "60f199509111e70000000067",
"name": "Medium",
"parent_id": "60f199509111e70000000069",
"active": true,
"archived": false,
"attributes": {
"example": true
},
"currency": "USD",
"date_created": "2021-07-16T14:36:00.333Z",
"date_updated": "2021-07-16T14:36:00.333Z",
"images": [
{
"id": "5ca24abb9c077817e5fe2b37",
"caption": "Just a variant",
"file": {
"id": "5ca24abb9c077817e5fe2b38",
"length": 66764,
"md5": "99194f53bfdea832553e7fa8ae8fd80f",
"content_type": "image/png",
"url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
"width": 940,
"height": 600
}
}
],
"option_value_ids": [
"59764b54e68ba2330390319a"
],
"price": 18.99,
"sale": false,
"sale_price": null,
"sku": "EX2001",
"stock_level": 6
}
Create a new variant. Normally, variants are automatically created when product options are set.
Arguments
Human-friendly name of the variant. Defaults to the combined name of all options, for example, "Blue, Large" in the case of 2 options; color and size.
The id of the parent product.
An object containing custom attribute values. Overrides product attributes. See attributes for more details.
List of option value IDs that constitute the variant.
List price used by default when sale=false or sale_price is not defined. Overrides product price.
An active variant is visible to customers in a storefront. Otherwise, it will be hidden from view.
A variant is automatically archived when it has been sold in the past and product options are changed in a way that would cause the variant to be removed.
Cost of goods used to calculate gross margins. Overrides product cost.
List of images depicting the variant.
A brief description of the image.
An object representing the image file.
Price rules to override price and sale_price when conditions match quantity or account group in a cart. Overrides product prices
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Indicates the variant is on sale and sale_price is used by default when the product is added to a cart. Overrides product sale.
Sale price used by default when sale=true, overriding price. Overrides product sale price.
If specified, shipping is calculated based on this shipping weight. Otherwise, it will assume 1 lb/oz/kg depending on your default weight unit. Overrides product shipping weight.
Stock keeping unit (SKU) used to track inventory in a warehouse.
$ curl https://api.swell.store/products:variants \
-u store-id:secret-key \
-d parent_id=5ca24abb9c077817e5fe2b36
-d name="Blue, Small"
Response
{
"id": "5c8fb5e1ed2faf8c79da492a",
"parent_id": "5ca24abb9c077817e5fe2b36",
"name": "Blue, Small",
"active": true,
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z"
}
Retrieve an existing variant using the id that was returned when created.
Arguments
The id of the variant to retrieve.
Expanding link fields and child collections is performed using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Return only the specified fields in the result.
- For example fields=name,slug would return only the fields name and slug in the response.
Supports nested object and array fields using dot-notation
- For example items.product_id. The variant id is always returned.
Include one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
$ curl https://api.swell.store/products:variants/5c8fb5e1ed2faf8c79da492a \
-u store-id:secret-key
Response
{
"id": "5c8fb5e1ed2faf8c79da492a",
"parent_id": "5ca24abb9c077817e5fe2b36",
"name": "Blue, Small",
"active": true,
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z"
"date_updated": "2019-04-01T00:00:00.000Z",
}
Update an existing product using the ID that was returned when created. Updating performs a merge operation. To explicitly override values such as arrays, use the $set operator.
Arguments
Unique identifier for the variant.
The id of the parent product.
An active variant is visible to customers in a storefront, otherwise it will be hidden from view.
An object containing custom attribute values. Overrides product attributes. See attributes for more details.
Human-friendly name of the variant. Defaults to the combined name of all options, for example, "Blue, Large" in the case of 2 options; color and size.
List price used by default when sale=false or sale_price is not defined. Overrides product price.
A variant is automatically archived when it has been sold in the past and product options are changed in a way that would cause the variant to be removed.
Cost of goods used to calculate gross margins. Overrides product cost.
List of images depicting the variant.
A brief description of the image.
An object representing the image file.
A reference to the raw file data.
Optional file name.
Price rules to override price and sale_price when conditions match quantity or account group in a cart. Overrides product prices.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Indicates the variant is on sale and sale_price is used by default when the product is added to a cart. Overrides product sale.
Sale price used by default when sale=true, overriding price. Overrides product sale price.
If specified, shipping is calculated based on this shipping weight. Otherwise it will assume 1 lb/oz/kg depending on your default weight unit. Overrides product shipping weight.
Stock keeping unit (SKU) used to track inventory in a warehouse.
$ curl https://api.swell.store/products:variants/5c8fb5e1ed2faf8c79da492a \
-u store-id:secret-key \
-d price=19.98 \
-X PUT
Response
{
"id": "5c8fb5e1ed2faf8c79da492a",
"parent_id": "5ca24abb9c077817e5fe2b36",
"name": "Blue, Small",
"active": true,
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"date_updated": "2019-04-01T00:00:00.000Z",
"price": 19.98
}
Return a list of product variants.
Arguments
Expand link fields and child collections by using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Returns only the specified fields in the result.
- For example fields=name,slug would return only the fields name and slug in the response.
Supports nested object and array fields using dot-notation.
- For example, items.product_id. The product id is always returned.
Include one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.
The page number of results to return given the specified or default limit.
A text search is performed using the search argument. Searchable fields are defined by the model.
- For example, search=red would return records containing the word "red" anywhere in the defined text fields.
See searching for more details.
Expression to sort results by using a format similar to a SQL sort statement.
- For example, sort=name asc would return records sorted by name ascending.
See sorting for more details.
An object with criteria to filter the result.
- For example, active=true would return records containing a field active with the value true.
It's also possible to use query operators, for example, $eq, $ne, $gt, and more.
See querying for more details.
$ curl https://api.swell.store/products:variants?where[active]=true&limit=25&page=1 \
-u store-id:secret-key \
-G
Response
{
"count":