Fourthwall APIs (v1.0)
Download OpenAPI specification:Download
We are excited to offer you access to our Open API, allowing you to integrate our services seamlessly with your applications.
However, kindly note that the creation of API credentials is reserved for users with the SUPER ADMIN role for security reasons.
To obtain the required credentials, please follow these steps:
- Log in to your shop dashboard with your SUPER ADMIN account.
- In the left panel, navigate to the "Settings" section.
- Click on the "For Developers" tab.
Creating API User
If API credentials haven't been generated yet, you will find a "Create API User" button under the "Open API" section. Click on it, and shortly after, the Username and Password for the Open API User will be provided.
Important Security Note
Keep your API credentials confidential and do not share them with unauthorized personnel. These credentials grant access to sensitive data and actions within our system. Always use HTTPS/SSL for encrypted communication when making API requests.
To ensure fair usage and maintain optimal system performance, we have implemented rate limiting for API requests. This means that each user is allowed a maximum of 100 requests within a 10-second rolling window.
What it means for you:
- You can make up to 100 requests within any 10-second period.
- If you exceed this limit, any additional requests will be delayed until the 10-second window is reset.
Please plan your API usage accordingly to avoid interruptions and ensure the smooth functioning of our services.
Need to check webhooks? The documentation provides comprehensive guidance.
If you're just looking to read public product information, you do not need to use Open API. All sites publish a Merchant Center Feed under an RSS address:
{$shop_url}/.well-known/merchant-center/rss.xml
Example: for https://shop.fourthwall.com the RSS feed url would be https://shop.fourthwall.com/.well-known/merchant-center/rss.xml
Create giveaway links
Creates a new package with specified number of giveaway links
Authorizations:
Request Body schema: application/json
productId required | string <uuid> |
number required | integer <int32> |
Responses
Request samples
- Payload
{- "productId": "dcd53ddb-8104-4e48-8cc0-5df1088c6113",
- "number": 0
}
Response samples
- 200
{- "packageId": "gpg_EdJvIXu3SEiXe_QkPavHSA",
- "giveawayLinks": [
- {
- "status": "AVAILABLE",
- "id": "gft_EdJvIXu3SEiXe_QkPavHSA",
- "link": "string",
- "productId": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "createdAt": "2020-08-13T09:05:36.939Z"
}
]
}
Get giveaway links
Returns all giveaway links for packageId
Authorizations:
path Parameters
packageId required | string Example: 00aa4abd-5778-4199-8161-0b49b2f212e5 |
Responses
Response samples
- 200
{- "packageId": "gpg_EdJvIXu3SEiXe_QkPavHSA",
- "giveawayLinks": [
- {
- "status": "AVAILABLE",
- "id": "gft_EdJvIXu3SEiXe_QkPavHSA",
- "link": "string",
- "productId": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "createdAt": "2020-08-13T09:05:36.939Z"
}
]
}
Get Thank You by id
Get Thank You details
Authorizations:
path Parameters
thankYouId required | string Example: ty_EdJvIXu3SEiXe_QkPavHSA |
Responses
Response samples
- 200
{- "id": "ty_EdJvIXu3SEiXe_QkPavHSA",
- "contribution": {
- "type": "ORDER",
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "shopId": "sh_c689d374-22ca-43d3-8d29-9ef0805cc4cb",
- "supporter": {
- "email": "supporter@fourthwall.com",
- "username": "Johnny123",
- "message": "Sample message"
}
}
}
Get all products (offers)
Returns all products with pagination
Authorizations:
query Parameters
page | integer <int32> Default: 0 Example: page=5 |
size | integer <int32> Default: 20 Example: size=5 |
Responses
Response samples
- 200
{- "results": [
- {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "name": "My t-shirt",
- "slug": "my-t-shirt",
- "description": "My t-shirt description",
- "state": {
- "type": "AVAILABLE"
}, - "access": {
- "type": "PUBLIC"
}, - "images": [
- {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "width": 800,
- "height": 600
}
], - "variants": [
- {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "name": "My t-shirt - Black, L",
- "sku": "WDEK-DRE200L",
- "unitPrice": {
- "value": 10,
- "currency": "USD"
}, - "attributes": {
- "description": "Black, L",
- "color": {
- "name": "Black",
- "swatch": "#000000"
}, - "size": {
- "name": "L"
}
}, - "stock": {
- "type": "UNLIMITED"
}, - "weight": {
- "value": 1,
- "unit": "kg"
}, - "dimensions": {
- "length": 1,
- "width": 2,
- "height": 3,
- "unit": "cm"
}, - "images": [
- {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "width": 800,
- "height": 600
}
]
}
], - "createdAt": "2020-08-13T09:05:36.939Z",
- "updatedAt": "2020-08-13T09:05:36.939Z"
}
]
}
Get product (offer) by id
Returns product by id
Authorizations:
path Parameters
productId required | string Example: 00aa4abd-5778-4199-8161-0b49b2f212e5 |
Responses
Response samples
- 200
{- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "name": "My t-shirt",
- "slug": "my-t-shirt",
- "description": "My t-shirt description",
- "state": {
- "type": "AVAILABLE"
}, - "access": {
- "type": "PUBLIC"
}, - "images": [
- {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "width": 800,
- "height": 600
}
], - "variants": [
- {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "name": "My t-shirt - Black, L",
- "sku": "WDEK-DRE200L",
- "unitPrice": {
- "value": 10,
- "currency": "USD"
}, - "attributes": {
- "description": "Black, L",
- "color": {
- "name": "Black",
- "swatch": "#000000"
}, - "size": {
- "name": "L"
}
}, - "stock": {
- "type": "UNLIMITED"
}, - "weight": {
- "value": 1,
- "unit": "kg"
}, - "dimensions": {
- "length": 1,
- "width": 2,
- "height": 3,
- "unit": "cm"
}, - "images": [
- {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "width": 800,
- "height": 600
}
]
}
], - "createdAt": "2020-08-13T09:05:36.939Z",
- "updatedAt": "2020-08-13T09:05:36.939Z"
}
Get all orders
Returns all orders with pagination
Authorizations:
query Parameters
page | integer <int32> Default: 0 Example: page=5 |
size | integer <int32> Default: 20 Example: size=5 |
Responses
Response samples
- 200
{- "results": [
- {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "shopId": "sh_c689d374-22ca-43d3-8d29-9ef0805cc4cb",
- "friendlyId": "D3XZFWPP",
- "checkoutId": "ch_BV44UYrXQA2T_Xcf1288tw",
- "status": "CONFIRMED",
- "email": "supporter@fourthwall.com",
- "emailMarketingOptIn": true,
- "username": "Johnny123",
- "message": "Sample message",
- "amounts": {
- "subtotal": {
- "value": 10,
- "currency": "USD"
}, - "shipping": {
- "value": 10,
- "currency": "USD"
}, - "tax": {
- "value": 10,
- "currency": "USD"
}, - "donation": {
- "value": 10,
- "currency": "USD"
}, - "discount": {
- "value": 10,
- "currency": "USD"
}, - "total": {
- "value": 10,
- "currency": "USD"
}
}, - "billing": {
- "address": {
- "name": "Joe Doe",
- "address1": "Main Street 1",
- "address2": "string",
- "city": "San Francisco",
- "state": "CA",
- "country": "US",
- "zip": "12345",
- "phone": "123456789"
}
}, - "shipping": {
- "address": {
- "name": "Joe Doe",
- "address1": "Main Street 1",
- "address2": "string",
- "city": "San Francisco",
- "state": "CA",
- "country": "US",
- "zip": "12345",
- "phone": "123456789"
}
}, - "offers": [
- {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "name": "My t-shirt",
- "slug": "my-t-shirt",
- "description": "My t-shirt description",
- "primaryImage": {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "width": 800,
- "height": 600
}, - "variant": {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "name": "My t-shirt - Black, L",
- "sku": "WDEK-DRE200L",
- "unitPrice": {
- "value": 10,
- "currency": "USD"
}, - "attributes": {
- "description": "Black, L",
- "color": {
- "name": "Black",
- "swatch": "#000000"
}, - "size": {
- "name": "L"
}
}, - "quantity": 5,
- "price": {
- "value": 10,
- "currency": "USD"
}, - "weight": {
- "value": 1,
- "unit": "kg"
}, - "dimensions": {
- "length": 1,
- "width": 2,
- "height": 3,
- "unit": "cm"
}
}
}
], - "source": {
- "type": "ORDER"
}, - "createdAt": "2020-08-13T09:05:36.939Z",
- "updatedAt": "2020-08-13T09:05:36.939Z"
}
]
}
Get order by id
Returns order by id
Authorizations:
path Parameters
orderId required | string Example: 00aa4abd-5778-4199-8161-0b49b2f212e5 |
Responses
Response samples
- 200
{- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "shopId": "sh_c689d374-22ca-43d3-8d29-9ef0805cc4cb",
- "friendlyId": "D3XZFWPP",
- "checkoutId": "ch_BV44UYrXQA2T_Xcf1288tw",
- "status": "CONFIRMED",
- "email": "supporter@fourthwall.com",
- "emailMarketingOptIn": true,
- "username": "Johnny123",
- "message": "Sample message",
- "amounts": {
- "subtotal": {
- "value": 10,
- "currency": "USD"
}, - "shipping": {
- "value": 10,
- "currency": "USD"
}, - "tax": {
- "value": 10,
- "currency": "USD"
}, - "donation": {
- "value": 10,
- "currency": "USD"
}, - "discount": {
- "value": 10,
- "currency": "USD"
}, - "total": {
- "value": 10,
- "currency": "USD"
}
}, - "billing": {
- "address": {
- "name": "Joe Doe",
- "address1": "Main Street 1",
- "address2": "string",
- "city": "San Francisco",
- "state": "CA",
- "country": "US",
- "zip": "12345",
- "phone": "123456789"
}
}, - "shipping": {
- "address": {
- "name": "Joe Doe",
- "address1": "Main Street 1",
- "address2": "string",
- "city": "San Francisco",
- "state": "CA",
- "country": "US",
- "zip": "12345",
- "phone": "123456789"
}
}, - "offers": [
- {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "name": "My t-shirt",
- "slug": "my-t-shirt",
- "description": "My t-shirt description",
- "primaryImage": {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "width": 800,
- "height": 600
}, - "variant": {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "name": "My t-shirt - Black, L",
- "sku": "WDEK-DRE200L",
- "unitPrice": {
- "value": 10,
- "currency": "USD"
}, - "attributes": {
- "description": "Black, L",
- "color": {
- "name": "Black",
- "swatch": "#000000"
}, - "size": {
- "name": "L"
}
}, - "quantity": 5,
- "price": {
- "value": 10,
- "currency": "USD"
}, - "weight": {
- "value": 1,
- "unit": "kg"
}, - "dimensions": {
- "length": 1,
- "width": 2,
- "height": 3,
- "unit": "cm"
}
}
}
], - "source": {
- "type": "ORDER"
}, - "createdAt": "2020-08-13T09:05:36.939Z",
- "updatedAt": "2020-08-13T09:05:36.939Z"
}
Get gift purchase by id
Returns gift purchase details by id
Authorizations:
path Parameters
giftPurchaseId required | string Example: giv_EdJvIXu3SEiXe_QkPavHSA |
Responses
Response samples
- 200
{- "id": "giv_EdJvIXu3SEiXe_QkPavHSA",
- "friendlyId": "D3XZFWPP",
- "shopId": "sh_c689d374-22ca-43d3-8d29-9ef0805cc4cb",
- "offer": {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "name": "My t-shirt",
- "slug": "my-t-shirt",
- "description": "My t-shirt description",
- "primaryImage": {
- "id": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "width": 800,
- "height": 600
}
}, - "amounts": {
- "subtotal": {
- "value": 10,
- "currency": "USD"
}, - "tax": {
- "value": 10,
- "currency": "USD"
}, - "total": {
- "value": 10,
- "currency": "USD"
}, - "profit": {
- "value": 10,
- "currency": "USD"
}, - "prepaidShipping": {
- "value": 10,
- "currency": "USD"
}
}, - "email": "supporter@fourthwall.com",
- "username": "Johnny123",
- "message": "Sample message",
- "gifts": [
- {
- "status": "REDEEMED",
- "id": "gft_EdJvIXu3SEiXe_QkPavHSA",
- "orderId": "00aa4abd-5778-4199-8161-0b49b2f212e5",
- "orderFriendlyId": "D3XZFWPP",
- "winner": {
- "email": "supporter@fourthwall.com",
- "username": "Johnny123",
- "selectedAt": "2020-08-13T09:05:36.939Z"
}
}
], - "createdAt": "2019-08-24T14:15:22Z"
}
Get all donations
Returns all donations with pagination
Authorizations:
query Parameters
page | integer <int32> Default: 0 Example: page=5 |
size | integer <int32> Default: 20 Example: size=5 |
Responses
Response samples
- 200
{- "results": [
- {
- "id": "don_Kpcjx4HIQ1e4bTIOjX9CsA",
- "shopId": "sh_c689d374-22ca-43d3-8d29-9ef0805cc4cb",
- "status": "OPEN",
- "email": "supporter@fourthwall.com",
- "username": "Johnny123",
- "message": "Sample message",
- "amounts": {
- "total": {
- "value": 10,
- "currency": "USD"
}
}, - "createdAt": "2020-08-13T09:05:36.939Z",
- "updatedAt": "2020-08-13T09:05:36.939Z"
}
]
}
Get donation by id
Returns donation by id
Authorizations:
path Parameters
donationId required | string Example: 00aa4abd-5778-4199-8161-0b49b2f212e5 |
Responses
Response samples
- 200
{- "id": "don_Kpcjx4HIQ1e4bTIOjX9CsA",
- "shopId": "sh_c689d374-22ca-43d3-8d29-9ef0805cc4cb",
- "status": "OPEN",
- "email": "supporter@fourthwall.com",
- "username": "Johnny123",
- "message": "Sample message",
- "amounts": {
- "total": {
- "value": 10,
- "currency": "USD"
}
}, - "createdAt": "2020-08-13T09:05:36.939Z",
- "updatedAt": "2020-08-13T09:05:36.939Z"
}