Public storefront access to a shop's collections - list all collections, get a collection by slug, and list the products within a collection - plus shop information for headless commerce front ends.
openapi: 3.1.0
info:
title: Fourthwall API
description: >-
Representative OpenAPI description of Fourthwall's public creator commerce
APIs. Fourthwall exposes two HTTP surfaces: a public Storefront API
(authenticated with a storefront token) for building headless shops, and a
Platform / Open API (authenticated with a shop API key via HTTP Basic Auth,
or OAuth 2.0 for multi-shop apps) for managing orders, products,
collections, promotions, gifting, memberships, and webhooks. This document
is a faithful, representative subset for cataloging; consult
https://docs.fourthwall.com for the complete, authoritative reference.
termsOfService: https://fourthwall.com/terms-of-service
contact:
name: Fourthwall
url: https://fourthwall.com
version: v1
servers:
- url: https://storefront-api.fourthwall.com
description: Storefront API (public storefront token)
- url: https://api.fourthwall.com
description: Platform / Open API (shop API key or OAuth)
tags:
- name: Storefront Products
- name: Storefront Collections
- name: Storefront Shop
- name: Storefront Carts
- name: Orders
- name: Products
- name: Collections
- name: Promotions
- name: Gifting
- name: Giveaways
- name: Memberships
- name: Webhooks
paths:
/v1/products/{slug}:
get:
operationId: getStorefrontProduct
tags:
- Storefront Products
summary: Get a product by slug
security:
- storefrontToken: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
- name: storefront_token
in: query
required: true
schema:
type: string
responses:
'200':
description: The product (offer).
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
/v1/collections:
get:
operationId: getStorefrontCollections
tags:
- Storefront Collections
summary: Get all collections
security:
- storefrontToken: []
parameters:
- name: storefront_token
in: query
required: true
schema:
type: string
responses:
'200':
description: A list of collections.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Collection'
/v1/collections/{slug}:
get:
operationId: getStorefrontCollection
tags:
- Storefront Collections
summary: Get a collection
security:
- storefrontToken: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
- name: storefront_token
in: query
required: true
schema:
type: string
responses:
'200':
description: The collection.
content:
application/json:
schema:
$ref: '#/components/schemas/Collection'
/v1/collections/{slug}/products:
get:
operationId: getStorefrontCollectionProducts
tags:
- Storefront Collections
summary: Get products (offers) in a collection
security:
- storefrontToken: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
- name: storefront_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Products in the collection.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Product'
/v1/shop:
get:
operationId: getStorefrontShop
tags:
- Storefront Shop
summary: Get shop information
security:
- storefrontToken: []
parameters:
- name: storefront_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Shop information.
content:
application/json:
schema:
$ref: '#/components/schemas/Shop'
/v1/carts:
post:
operationId: createCart
tags:
- Storefront Carts
summary: Create cart
security:
- storefrontToken: []
parameters:
- name: storefront_token
in: query
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartCreateRequest'
responses:
'200':
description: The created cart.
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/v1/carts/{cartId}:
get:
operationId: getCart
tags:
- Storefront Carts
summary: Get cart by id
security:
- storefrontToken: []
parameters:
- name: cartId
in: path
required: true
schema:
type: string
- name: storefront_token
in: query
required: true
schema:
type: string
responses:
'200':
description: The cart.
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/v1/carts/{cartId}/add:
post:
operationId: addToCart
tags:
- Storefront Carts
summary: Add to cart
security:
- storefrontToken: []
parameters:
- name: cartId
in: path
required: true
schema:
type: string
- name: storefront_token
in: query
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartItemsRequest'
responses:
'200':
description: The updated cart.
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/v1/carts/{cartId}/change:
post:
operationId: changeCartItems
tags:
- Storefront Carts
summary: Change cart items quantity
security:
- storefrontToken: []
parameters:
- name: cartId
in: path
required: true
schema:
type: string
- name: storefront_token
in: query
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartItemsRequest'
responses:
'200':
description: The updated cart.
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/v1/carts/{cartId}/remove:
post:
operationId: removeFromCart
tags:
- Storefront Carts
summary: Remove from cart
security:
- storefrontToken: []
parameters:
- name: cartId
in: path
required: true
schema:
type: string
- name: storefront_token
in: query
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartItemsRequest'
responses:
'200':
description: The updated cart.
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/open-api/v1.0/order:
get:
operationId: getOrders
tags:
- Orders
summary: Get all orders
security:
- basicAuth: []
- oauth: [order_read]
responses:
'200':
description: A paginated list of orders.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderList'
/open-api/v1.0/order/{orderId}:
get:
operationId: getOrder
tags:
- Orders
summary: Get order by id
security:
- basicAuth: []
- oauth: [order_read]
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: The order.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
/open-api/v1.0/order/by-friendly-id/{friendlyId}:
get:
operationId: getOrderByFriendlyId
tags:
- Orders
summary: Get order by friendly id
security:
- basicAuth: []
- oauth: [order_read]
parameters:
- name: friendlyId
in: path
required: true
schema:
type: string
responses:
'200':
description: The order.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
/open-api/v1.0/order/{orderId}/downloaded:
put:
operationId: markOrderDownloaded
tags:
- Orders
summary: Mark digital download as downloaded
security:
- basicAuth: []
- oauth: [order_write]
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: Updated.
/open-api/v1.0/products:
get:
operationId: getProducts
tags:
- Products
summary: Get all products (offers)
security:
- basicAuth: []
- oauth: [offer_read]
responses:
'200':
description: A paginated list of products.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Product'
post:
operationId: createProduct
tags:
- Products
summary: Create a product
security:
- basicAuth: []
- oauth: [offer_write]
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The created product.
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
/open-api/v1.0/products/{productId}:
get:
operationId: getProduct
tags:
- Products
summary: Get product (offer) by id
security:
- basicAuth: []
- oauth: [offer_read]
parameters:
- name: productId
in: path
required: true
schema:
type: string
responses:
'200':
description: The product.
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
delete:
operationId: archiveProduct
tags:
- Products
summary: Archive a product (offer)
security:
- basicAuth: []
- oauth: [offer_write]
parameters:
- name: productId
in: path
required: true
schema:
type: string
responses:
'200':
description: Archived.
/open-api/v1.0/products/{productId}/inventory:
get:
operationId: getProductInventory
tags:
- Products
summary: Get product (offer) inventory by id
security:
- basicAuth: []
- oauth: [offer_read]
parameters:
- name: productId
in: path
required: true
schema:
type: string
responses:
'200':
description: Inventory levels.
/open-api/v1.0/collections:
get:
operationId: getCollections
tags:
- Collections
summary: Get all collections
security:
- basicAuth: []
- oauth: [offer_read]
responses:
'200':
description: A list of collections.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Collection'
post:
operationId: createCollection
tags:
- Collections
summary: Create a new collection
security:
- basicAuth: []
- oauth: [offer_write]
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The created collection.
content:
application/json:
schema:
$ref: '#/components/schemas/Collection'
/open-api/v1.0/collections/{collectionIdOrSlug}:
get:
operationId: getCollectionByIdOrSlug
tags:
- Collections
summary: Get collection by ID or slug
security:
- basicAuth: []
- oauth: [offer_read]
parameters:
- name: collectionIdOrSlug
in: path
required: true
schema:
type: string
responses:
'200':
description: The collection.
content:
application/json:
schema:
$ref: '#/components/schemas/Collection'
/open-api/v1.0/collections/{collectionId}/products:
get:
operationId: getCollectionProducts
tags:
- Collections
summary: Get products in a collection
security:
- basicAuth: []
- oauth: [offer_read]
parameters:
- name: collectionId
in: path
required: true
schema:
type: string
responses:
'200':
description: Products in the collection.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Product'
put:
operationId: setCollectionProducts
tags:
- Collections
summary: Set collection products
security:
- basicAuth: []
- oauth: [offer_write]
parameters:
- name: collectionId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: Updated.
/open-api/v1.0/promotions:
get:
operationId: getPromotions
tags:
- Promotions
summary: Get all promotions
security:
- basicAuth: []
- oauth: [promotions_read]
responses:
'200':
description: A list of promotions.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Promotion'
post:
operationId: createPromotion
tags:
- Promotions
summary: Create a promotion
security:
- basicAuth: []
- oauth: [promotions_write]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Promotion'
responses:
'200':
description: The created promotion.
content:
application/json:
schema:
$ref: '#/components/schemas/Promotion'
/open-api/v1.0/promotions/{promotionId}:
get:
operationId: getPromotion
tags:
- Promotions
summary: Get a promotion by id
security:
- basicAuth: []
- oauth: [promotions_read]
parameters:
- name: promotionId
in: path
required: true
schema:
type: string
responses:
'200':
description: The promotion.
content:
application/json:
schema:
$ref: '#/components/schemas/Promotion'
put:
operationId: updatePromotion
tags:
- Promotions
summary: Update a promotion
security:
- basicAuth: []
- oauth: [promotions_write]
parameters:
- name: promotionId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Promotion'
responses:
'200':
description: The updated promotion.
content:
application/json:
schema:
$ref: '#/components/schemas/Promotion'
/open-api/v1.0/gifting/config:
get:
operationId: getGiftingConfig
tags:
- Gifting
summary: Get gifting config
security:
- basicAuth: []
- oauth: [offer_read]
responses:
'200':
description: The gifting configuration.
put:
operationId: updateGiftingConfig
tags:
- Gifting
summary: Update gifting config
security:
- basicAuth: []
- oauth: [offer_write]
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: Updated.
/open-api/v1.0/gifting/checkout:
post:
operationId: createGiftingCheckout
tags:
- Gifting
summary: Create a gifting checkout
security:
- basicAuth: []
- oauth: [offer_write]
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The created gifting checkout.
/open-api/v1.0/gifting/draw/{id}:
get:
operationId: getGiftDraw
tags:
- Gifting
summary: Get draw
security:
- basicAuth: []
- oauth: [offer_read]
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: The draw.
/open-api/v1.0/gifting/draw/{id}/finish:
put:
operationId: finishGiftDraw
tags:
- Gifting
summary: Finish draw
security:
- basicAuth: []
- oauth: [offer_write]
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Finished.
/open-api/v1.0/giveaways/giveaways:
post:
operationId: createGiveaway
tags:
- Giveaways
summary: Create a new giveaway
security:
- basicAuth: []
- oauth: [giveaway_write]
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The created giveaway.
/open-api/v1.0/memberships/tiers:
get:
operationId: listMembershipTiers
tags:
- Memberships
summary: List membership tiers
security:
- basicAuth: []
- oauth: [memberships_read]
responses:
'200':
description: A list of membership tiers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MembershipTier'
/open-api/v1.0/memberships/members:
get:
operationId: listMembers
tags:
- Memberships
summary: List members
security:
- basicAuth: []
- oauth: [memberships_read]
responses:
'200':
description: A list of members.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Member'
/open-api/v1.0/memberships/members/{id}:
get:
operationId: getMember
tags:
- Memberships
summary: Get member
security:
- basicAuth: []
- oauth: [memberships_read]
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: The member.
content:
application/json:
schema:
$ref: '#/components/schemas/Member'
/open-api/v1.0/webhooks:
get:
operationId: getWebhooks
tags:
- Webhooks
summary: Get webhooks
security:
- basicAuth: []
- oauth: [webhook_read]
responses:
'200':
description: A list of webhook configurations.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WebhookConfiguration'
post:
operationId: createWebhook
tags:
- Webhooks
summary: Create a webhook
security:
- basicAuth: []
- oauth: [webhook_write]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookConfigurationCreateRequest'
responses:
'200':
description: The created webhook configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookConfiguration'
/open-api/v1.0/webhooks/{webhookConfigurationId}:
get:
operationId: getWebhook
tags:
- Webhooks
summary: Get a webhook
security:
- basicAuth: []
- oauth: [webhook_read]
parameters:
- name: webhookConfigurationId
in: path
required: true
schema:
type: string
responses:
'200':
description: The webhook configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookConfiguration'
put:
operationId: updateWebhook
tags:
- Webhooks
summary: Update a webhook
security:
- basicAuth: []
- oauth: [webhook_write]
parameters:
- name: webhookConfigurationId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookConfigurationCreateRequest'
responses:
'200':
description: The updated webhook configuration.
delete:
operationId: deleteWebhook
tags:
- Webhooks
summary: Delete a webhook
security:
- basicAuth: []
- oauth: [webhook_write]
parameters:
- name: webhookConfigurationId
in: path
required: true
schema:
type: string
responses:
'204':
description: Deleted.
/open-api/v1.0/webhook-events:
get:
operationId: getWebhookEvents
tags:
- Webhooks
summary: Get webhook events
security:
- basicAuth: []
- oauth: [webhook_read]
responses:
'200':
description: A list of delivered webhook events.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WebhookEvent'
components:
securitySchemes:
storefrontToken:
type: apiKey
in: query
name: storefront_token
description: >-
Public storefront token obtained from Settings > For Developers, passed
as the storefront_token query parameter on Storefront API requests.
basicAuth:
type: http
scheme: basic
description: >-
Shop API key used with HTTP Basic Authentication against the Platform
(Open) API.
oauth:
type: oauth2
description: OAuth 2.0 for multi-shop platform apps.
flows:
authorizationCode:
authorizationUrl: https://auth.fourthwall.com/auth/realms/Fourthwall/protocol/openid-connect/auth
tokenUrl: https://api.fourthwall.com/open-api/v1.0/platform/token
scopes:
order_read: Read orders
order_write: Write orders and fulfillments
offer_read: Read products, collections, and gifting
offer_write: Write products, collections, and gifting
promotions_read: Read promotions
promotions_write: Write promotions
giveaway_read: Read giveaways
giveaway_write: Write giveaways
memberships_read: Read memberships
memberships_write: Write memberships
webhook_read: Read webhooks
webhook_write: Write webhooks
donation_read: Read donations
shop_read: Read shop information
schemas:
Shop:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
Product:
type: object
description: A Fourthwall product (offer).
properties:
id:
type: string
name:
type: string
slug:
type: string
description:
type: string
state:
type: string
variants:
type: array
items:
$ref: '#/components/schemas/Variant'
Variant:
type: object
properties:
id:
type: string
name:
type: string
sku:
type: string
price:
$ref: '#/components/schemas/Money'
Collection:
type: object
properties:
id:
type: string
name:
type: string
slug:
type: string
description:
type: string
Cart:
type: object
properties:
id:
type: string
items:
type: array
items:
$ref: '#/components/schemas/CartItem'
CartItem:
type: object
properties:
variantId:
type: string
quantity:
type: integer
CartCreateRequest:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/CartItem'
CartItemsRequest:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/CartItem'
Order:
type: object
properties:
id:
type: string
friendlyId:
type: string
status:
type: string
email:
type: string
total:
$ref: '#/components/schemas/Money'
OrderList:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Order'
paging:
type: object
Promotion:
type: object
properties:
id:
type: string
name:
type: string
type:
type: string
status:
type: string
MembershipTier:
type: object
properties:
id:
type: string
name:
type: string
price:
$ref: '#/components/schemas/Money'
Member:
type: object
properties:
id:
type: string
email:
type: string
tierId:
type: string
status:
type: string
Money:
type: object
properties:
value:
type: number
currency:
type: string
WebhookConfiguration:
type: object
properties:
id:
type: string
url:
type: string
allowedTypes:
type: array
items:
$ref: '#/components/schemas/WebhookEventType'
WebhookConfigurationCreateRequest:
type: object
required:
- url
- allowedTypes
properties:
url:
type: string
allowedTypes:
type: array
items:
$ref: '#/components/schemas/WebhookEventType'
WebhookEvent:
type: object
properties:
id:
type: string
type:
$ref: '#/components/schemas/WebhookEventType'
payload:
type: object
WebhookEventType:
type: string
enum:
- ORDER_PLACED
- ORDER_UPDATED
- GIFT_PURCHASE
- PRODUCT_CREATED
- PRODUCT_UPDATED
- DONATION
- SUBSCRIPTION_PURCHASED
- SUBSCRIPTION_EXPIRED
- SUBSCRIPTION_CHANGED
- NEWSLETTER_SUBSCRIBED
- THANK_YOU_SENT
- GIFT_DRAW_STARTED
- GIFT_DRAW_ENDED
- PROMOTION_CREATED
- PROMOTION_UPDATED
- PROMOTION_STATUS_CHANGED
- PLATFORM_APP_DISCONNECTED
- MEMBERSHIP_POST_UPSERTED
- MEMBERSHIP_SERIES_UPSERTED
- MEMBERSHIP_SERIES_DELETED
- MEMBERSHIP_TAG_CREATED
- MEMBERSHIP_TAG_UPDATED
- MEMBERSHIP_TAG_DELETED
- MEMBERSHIP_TIER_UPSERTED
- MEMBERSHIP_TIER_DELETED
- COLLECTION_UPDATED
- CART_ABANDONED_1H
- CART_ABANDONED_24H
- CART_ABANDONED_72H