SnapSell External API & Sale Webhooks

https://snapsell.org/docs/api
Admin
SnapSell External API & Sale Webhooks provides comprehensive documentation for integrating with...
Tokens:11,338
Snippets:67
Trust Score:5.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Create Gallery Response

Source: https://snapsell.org/docs/api

Example response after successfully creating a gallery. Includes a success message, the created gallery object, and a payment URL.

```json
{
  "message": "Gallery created successfully.",
  "gallery": {
    "id": 42,
    "user_id": 7,
    "title": "Summer pack",
    "description": "Optional",
    "price": "9.99",
    "hash": "8pmTfurIG3",
    "status": "active",
    "is_deleted": false,
    "is_collection": false,
    "is_adult_content": false,
    "views": 0,
    "created_at": "2026-06-13T11:22:05.000000Z",
    "updated_at": "2026-06-13T11:22:05.000000Z",
    "deleted_at": null
  },
  "payment_url": "https://snapsell.org/buy/8pmTfurIG3"
}
```

--------------------------------

### Get All Galleries Response

Source: https://snapsell.org/docs/api

Example response when retrieving all galleries belonging to an account. Includes gallery details and associated uploads.

```json
{
  "galleries": [
    {
      "id": 42,
      "user_id": 7,
      "title": "Summer pack",
      "description": "Optional",
      "price": "9.99",
      "hash": "SEf4rXKf9y",
      "status": "active",
      "is_deleted": false,
      "is_collection": false,
      "is_adult_content": false,
      "views": 0,
      "created_at": "2026-06-13T11:07:46.000000Z",
      "updated_at": "2026-06-13T11:07:46.000000Z",
      "deleted_at": null,
      "uploads_count": 2,
      "payment_url": "https://snapsell.org/buy/SEf4rXKf9y",
      "uploads": [
        {
          "id": 101,
          "product_id": "85de3406-3c8c-42ef-b0a7-d99b3b7fc249",
          "user_id": 7,
          "original_filename": "photo.png",
          "mime_type": "image/png",
          "file_size": 335872,
          "file_path_original": "users/7/products/DbzK5gk8TwAK21gwct2GZF49r8qdIuYC",
          "file_path_preview": null,
          "status": "processed",
          "storage_disk": "s3",
          "local_backup_path": null,
          "uploaded_to_s3_at": "2026-06-13T11:14:36.000000Z",
          "s3_upload_attempts": 0,
          "preview": null,
          "thumbnail": null,
          "created_at": "2026-06-13T11:13:42.000000Z",
          "updated_at": "2026-06-13T11:17:28.000000Z",
          "deleted_at": null,
          "pivot": {
            "gallery_id": 42,
            "upload_id": 101,
            "order": 0,
            "created_at": "2026-06-13T11:17:28.000000Z",
            "updated_at": "2026-06-13T11:17:28.000000Z"
          }
        }
      ]
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 15,
  "total": 1
}
```

--------------------------------

### List Galleries with Pagination

Source: https://snapsell.org/docs/api

Retrieve a list of galleries with custom pagination. This example shows how to request the second page with 30 items per page.

```bash
curl -sS "https://snapsell.org/api/external/v1/galleries?page=2&per_page=30" \
  -H "Authorization: Bearer YOUR_KEY_HERE"
```

--------------------------------

### Initialize Simple Upload

Source: https://snapsell.org/docs/api

Starts a file upload process by returning a presigned S3 PUT URL. This URL is valid for 24 hours and allows uploading the entire file in a single request.

```APIDOC
## POST https://snapsell.org/api/external/v1/uploads/simple/init

### Description
Start a file upload. Returns a presigned S3 `PUT` URL valid for up to 24 hours. No multipart setup required — you send the entire file in one `PUT`. Save the `upload.id` and the `url` from this response for the next two steps.

### Method
POST

### Endpoint
https://snapsell.org/api/external/v1/uploads/simple/init

### Parameters
#### Request Body
- **original_filename** (string) - Required - Max 512 characters.
- **mime_type** (string) - Required - Max 255 characters.
- **file_size** (integer) - Required - Size in bytes, between 1 and 5,368,709,120 (5 GiB max).

### Request Example
```json
{
  "original_filename": "photo.png",
  "mime_type": "image/png",
  "file_size": 335872
}
```

### Response
#### Success Response (201 Created)
- **message** (string) - Confirmation message.
- **upload** (object) - Details of the initiated upload.
  - **id** (integer) - Unique identifier for the upload.
  - **product_id** (string) - Associated product ID.
  - **user_id** (integer) - ID of the user initiating the upload.
  - **original_filename** (string) - Original name of the file.
  - **mime_type** (string) - MIME type of the file.
  - **file_size** (integer) - Size of the file in bytes.
  - **file_path_original** (string) - Path to the original file in storage.
  - **file_path_preview** (string) - Path to the preview image (null if not generated).
  - **status** (string) - Current status of the upload (e.g., "pending_direct_upload").
  - **storage_disk** (string) - The storage disk used (e.g., "s3").
  - **local_backup_path** (string) - Local backup path (null if not applicable).
  - **uploaded_to_s3_at** (string) - Timestamp of S3 upload (null if not uploaded).
  - **s3_upload_attempts** (integer) - Number of S3 upload attempts.
  - **preview** (string) - Preview information (null if not available).
  - **thumbnail** (string) - Thumbnail information (null if not available).
  - **created_at** (string) - Timestamp of creation.
  - **updated_at** (string) - Timestamp of last update.
  - **deleted_at** (string) - Timestamp of deletion (null if not deleted).
- **url** (string) - The presigned S3 PUT URL.
- **method** (string) - The HTTP method to use for the upload (PUT).
- **headers** (object) - Headers required for the S3 upload.
  - **Content-Type** (string) - The MIME type of the file.

### Response Example
```json
{
  "message": "PUT the file bytes to the url using the provided headers, then call complete.",
  "upload": {
    "id": 101,
    "product_id": "472e30a4-111f-4274-87ee-f447ae635937",
    "user_id": 7,
    "original_filename": "photo.png",
    "mime_type": "image/png",
    "file_size": 335872,
    "file_path_original": "users/7/products/DLbsWD2IWwZdlF60AyDb8ZPaj55bwi8U",
    "file_path_preview": null,
    "status": "pending_direct_upload",
    "storage_disk": "s3",
    "local_backup_path": null,
    "uploaded_to_s3_at": null,
    "s3_upload_attempts": 0,
    "preview": null,
    "thumbnail": null,
    "created_at": "2026-06-13T11:24:59.000000Z",
    "updated_at": "2026-06-13T11:24:59.000000Z",
    "deleted_at": null
  },
  "url": "https://your-bucket.s3.region.amazonaws.com/users/7/products/DLbsWD2IWwZdlF60AyDb8ZPaj55bwi8U?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "method": "PUT",
  "headers": {
    "Content-Type": "image/png"
  }
}
```
```

--------------------------------

### Initialize File Upload

Source: https://snapsell.org/docs/api

Call init to get a presigned S3 URL for uploading a file. Requires API key for authorization. The response contains the upload ID and the S3 PUT URL.

```bash
INIT=$(curl -sS -X POST "https://snapsell.org/api/external/v1/uploads/simple/init" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY_HERE" \
  -d '{
    "original_filename": "photo.png",
    "mime_type": "image/png",
    "file_size": 335872
  }')

UPLOAD_ID=$(echo $INIT | jq -r '.upload.id')
PUT_URL=$(echo $INIT | jq -r '.url')
```

--------------------------------

### Create Gallery Request Body

Source: https://snapsell.org/docs/api

Example request body for creating a new gallery. Requires title and price, with optional description and collection status.

```json
{
  "title": "Summer pack",
  "price": 9.99,
  "description": "Optional"
}
```

--------------------------------

### Get Gallery by Hash

Source: https://snapsell.org/docs/api

Retrieves a specific gallery using its hash.

```APIDOC
## GET /galleries/{gallery_hash}

### Description
Retrieves a specific gallery using its hash.

### Method
GET

### Endpoint
/galleries/{gallery_hash}

### Parameters
#### Path Parameters
- **gallery_hash** (string) - Required - The unique hash of the gallery.
```

--------------------------------

### Get Gallery by Hash

Source: https://snapsell.org/docs/api

Fetches a specific gallery using its unique hash, including all associated uploads.

```APIDOC
## GET /api/external/v1/galleries/{gallery_hash}

### Description
Fetch a single gallery with all its attached uploads.

### Method
GET

### Endpoint
https://snapsell.org/api/external/v1/galleries/{gallery_hash}

### Parameters
#### Path Parameters
- **gallery_hash** (string) - Required - The public hash of the gallery.
```

--------------------------------

### Gallery Response - 200 OK

Source: https://snapsell.org/docs/api

Example response showing a gallery object with associated uploads. This response is typically received after successfully creating or retrieving gallery information.

```json
{
  "gallery": {
    "id": 42,
    "user_id": 7,
    "title": "Summer pack",
    "description": "Optional",
    "price": "9.99",
    "hash": "SEf4rXKf9y",
    "status": "active",
    "is_deleted": false,
    "is_collection": false,
    "is_adult_content": false,
    "views": 0,
    "created_at": "2026-06-13T11:07:46.000000Z",
    "updated_at": "2026-06-13T11:07:46.000000Z",
    "deleted_at": null,
    "uploads": [
      {
        "id": 101,
        "product_id": "85de3406-3c8c-42ef-b0a7-d99b3b7fc249",
        "user_id": 7,
        "original_filename": "photo.png",
        "mime_type": "image/png",
        "file_size": 335872,
        "file_path_original": "users/7/products/DbzK5gk8TwAK21gwct2GZF49r8qdIuYC",
        "file_path_preview": null,
        "status": "processed",
        "storage_disk": "s3",
        "local_backup_path": null,
        "uploaded_to_s3_at": "2026-06-13T11:14:36.000000Z",
        "s3_upload_attempts": 0,
        "preview": null,
        "thumbnail": null,
        "created_at": "2026-06-13T11:13:42.000000Z",
        "updated_at": "2026-06-13T11:17:28.000000Z",
        "deleted_at": null,
        "pivot": {
          "gallery_id": 42,
          "upload_id": 101,
          "order": 0,
          "created_at": "2026-06-13T11:17:28.000000Z",
          "updated_at": "2026-06-13T11:17:28.000000Z"
        }
      }
    ]
  },
  "payment_url": "https://snapsell.org/buy/SEf4rXKf9y"
}
```

--------------------------------

### Get a gallery

Source: https://snapsell.org/docs/api

Retrieves details of a specific gallery, including its payment URL. This can be used to get the checkout page link.

```APIDOC
## GET /api/external/v1/galleries/{gallery_hash}

### Description
Retrieves details for a specific gallery, including the payment URL.

### Method
GET

### Endpoint
/api/external/v1/galleries/{gallery_hash}

### Parameters
#### Path Parameters
- **gallery_hash** (string) - Required - The hash of the gallery to retrieve.

### Response
#### Success Response (200)
- **payment_url** (string) - The URL for the gallery's payment page.
```

--------------------------------

### Get Gallery Payment Link

Source: https://snapsell.org/docs/api

Retrieve the payment URL for a gallery. This URL is the checkout page for buyers. It can be obtained by fetching the gallery details.

```bash
curl -sS "https://snapsell.org/api/external/v1/galleries/$GALLERY_HASH" \
  -H "Authorization: Bearer YOUR_KEY_HERE" \
| jq -r '.payment_url'
```

--------------------------------

### Example Webhook Payload

Source: https://snapsell.org/docs/api

This is the JSON payload structure received by your server for a completed sale event. It contains details about the transaction, gallery, and payment.

```json
{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "type": "gallery.sale.completed",
  "api_version": "2026-04-07",
  "created_at": "2026-04-07T12:00:00+00:00",
  "data": {
    "transaction_uuid": "...",
    "gallery_id": 1,
    "gallery_hash": "...",
    "gallery_title": "...",
    "amount": "19.99",
    "currency_code": "EUR",
    "seller_earning": "17.50",
    "buyer_email": "buyer@example.com",
    "payment_gateway": "stripe",
    "completed_at": "2026-04-07T12:00:00+00:00"
  }
}
```

--------------------------------

### Get All Galleries

Source: https://snapsell.org/docs/api

Retrieves all galleries associated with the authenticated account, ordered by creation date (newest first). Each gallery object includes details about its uploads and a payment URL. Galleries without any uploads are excluded from the results.

```APIDOC
## GET /api/external/v1/galleries

### Description
Returns all galleries belonging to your account, paginated newest first. Each gallery includes its uploads and a ready-to-share `payment_url`. Galleries with no uploads are excluded.

### Method
GET

### Endpoint
https://snapsell.org/api/external/v1/galleries

### Query Parameters
- **page** (integer) - Optional - Page number (default `1`)
- **per_page** (integer) - Optional - Results per page (default `15`, max `50`)

### Response - 200 OK
```json
{
  "galleries": [
    {
      "id": 42,
      "user_id": 7,
      "title": "Summer pack",
      "description": "Optional",
      "price": "9.99",
      "hash": "SEf4rXKf9y",
      "status": "active",
      "is_deleted": false,
      "is_collection": false,
      "is_adult_content": false,
      "views": 0,
      "created_at": "2026-06-13T11:07:46.000000Z",
      "updated_at": "2026-06-13T11:07:46.000000Z",
      "deleted_at": null,
      "uploads_count": 2,
      "payment_url": "https://snapsell.org/buy/SEf4rXKf9y",
      "uploads": [
        {
          "id": 101,
          "product_id": "85de3406-3c8c-42ef-b0a7-d99b3b7fc249",
          "user_id": 7,
          "original_filename": "photo.png",
          "mime_type": "image/png",
          "file_size": 335872,
          "file_path_original": "users/7/products/DbzK5gk8TwAK21gwct2GZF49r8qdIuYC",
          "file_path_preview": null,
          "status": "processed",
          "storage_disk": "s3",
          "local_backup_path": null,
          "uploaded_to_s3_at": "2026-06-13T11:14:36.000000Z",
          "s3_upload_attempts": 0,
          "preview": null,
          "thumbnail": null,
          "created_at": "2026-06-13T11:13:42.000000Z",
          "updated_at": "2026-06-13T11:17:28.000000Z",
          "deleted_at": null,
          "pivot": {
            "gallery_id": 42,
            "upload_id": 101,
            "order": 0,
            "created_at": "2026-06-13T11:17:28.000000Z",
            "updated_at": "2026-06-13T11:17:28.000000Z"
          }
        }
      ]
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 15,
  "total": 1
}
```
```

--------------------------------

### Create Gallery

Source: https://snapsell.org/docs/api

Create a new gallery to group files for purchase. Set a title, price, and description. The response contains the gallery hash.

```bash
GALLERY=$(curl -sS -X POST "https://snapsell.org/api/external/v1/galleries" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY_HERE" \
  -d '{
    "title": "Summer pack",
    "price": 9.99,
    "description": "My summer collection"
  }')

GALLERY_HASH=$(echo $GALLERY | jq -r '.gallery.hash')
```

--------------------------------

### Upload a file - Init

Source: https://snapsell.org/docs/api

Initializes a file upload process to obtain a presigned S3 URL. This is the first step in uploading a file.

```APIDOC
## POST /api/external/v1/uploads/simple/init

### Description
Initializes a file upload to get a presigned S3 URL.

### Method
POST

### Endpoint
/api/external/v1/uploads/simple/init

### Parameters
#### Request Body
- **original_filename** (string) - Required - The original name of the file.
- **mime_type** (string) - Required - The MIME type of the file.
- **file_size** (integer) - Required - The size of the file in bytes.

### Request Example
{
  "original_filename": "photo.png",
  "mime_type": "image/png",
  "file_size": 335872
}

### Response
#### Success Response (200)
- **upload.id** (string) - The ID of the upload.
- **url** (string) - The presigned S3 URL for uploading the file.
```

--------------------------------

### Create a gallery

Source: https://snapsell.org/docs/api

Creates a new gallery, which acts as a product for buyers. This includes setting a price and title.

```APIDOC
## POST /api/external/v1/galleries

### Description
Creates a new gallery with a title, price, and description.

### Method
POST

### Endpoint
/api/external/v1/galleries

### Parameters
#### Request Body
- **title** (string) - Required - The title of the gallery.
- **price** (number) - Required - The price of the gallery.
- **description** (string) - Optional - A description for the gallery.

### Request Example
{
  "title": "Summer pack",
  "price": 9.99,
  "description": "My summer collection"
}

### Response
#### Success Response (200)
- **gallery.hash** (string) - The unique hash of the created gallery.
```

--------------------------------

### Upload File to S3

Source: https://snapsell.org/docs/api

PUT the file directly to the S3 URL obtained from the init step. No authentication header is required for this step. A successful upload returns an empty 200 OK.

```bash
curl -sS -X PUT "$PUT_URL" \
  -H "Content-Type: image/png" \
  --upload-file /path/to/photo.png
```

--------------------------------

### Initialize Simple Upload

Source: https://snapsell.org/docs/api

Initializes a simple file upload process.

```APIDOC
## POST /uploads/simple/init

### Description
Initializes a simple file upload process.

### Method
POST

### Endpoint
/uploads/simple/init
```

--------------------------------

### Create Gallery

Source: https://snapsell.org/docs/api

Creates a new gallery.

```APIDOC
## POST /galleries

### Description
Creates a new gallery.

### Method
POST

### Endpoint
/galleries
```

--------------------------------

### List All Galleries

Source: https://snapsell.org/docs/api

Retrieve a list of all galleries associated with the API key. This command fetches the first page of results.

```bash
curl -sS "https://snapsell.org/api/external/v1/galleries" \
  -H "Authorization: Bearer YOUR_KEY_HERE"
```

--------------------------------

### Initialize File Upload

Source: https://snapsell.org/docs/api

Initiates a file upload by returning a presigned S3 PUT URL. This URL is valid for 24 hours and allows uploading the entire file in a single request. Save the upload ID and URL for subsequent steps.

```json
{
  "original_filename": "photo.png",
  "mime_type": "image/png",
  "file_size": 335872
}
```

--------------------------------

### Create Gallery

Source: https://snapsell.org/docs/api

Creates a new gallery. The response includes the newly created gallery object and a payment URL for buyers.

```APIDOC
## POST /api/external/v1/galleries

### Description
Create a new gallery. Returns the created gallery object and a checkout link your buyers can use to purchase.

### Method
POST

### Endpoint
https://snapsell.org/api/external/v1/galleries

### Request Body
- **title** (string) - Required - Maximum 255 characters.
- **price** (number) - Required - Minimum value of 5.
- **description** (string) - Optional.
- **is_collection** (boolean) - Optional - Defaults to `false`.

### Request Example
```json
{
  "title": "Summer pack",
  "price": 9.99,
  "description": "Optional"
}
```

### Response - 201 Created
```json
{
  "message": "Gallery created successfully.",
  "gallery": {
    "id": 42,
    "user_id": 7,
    "title": "Summer pack",
    "description": "Optional",
    "price": "9.99",
    "hash": "8pmTfurIG3",
    "status": "active",
    "is_deleted": false,
    "is_collection": false,
    "is_adult_content": false,
    "views": 0,
    "created_at": "2026-06-13T11:22:05.000000Z",
    "updated_at": "2026-06-13T11:22:05.000000Z",
    "deleted_at": null
  },
  "payment_url": "https://snapsell.org/buy/8pmTfurIG3"
}
```
```

--------------------------------

### Complete Simple Upload

Source: https://snapsell.org/docs/api

Notifies the server that the file upload to S3 has been successful. The server then verifies the file's existence, marks the upload as ready, and initiates preview generation.

```APIDOC
## POST https://snapsell.org/api/external/v1/uploads/simple/{upload_id}/complete

### Description
Notify the server that the S3 PUT succeeded. The server verifies the file exists on storage, marks the upload ready, and queues preview generation. The upload’s `id` is then ready to add to a gallery.

### Method
POST

### Endpoint
https://snapsell.org/api/external/v1/uploads/simple/{upload_id}/complete

### Parameters
#### Path Parameters
- **upload_id** (integer) - Required - The ID of the upload initiated in the previous step.

### Request Body
None required.

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message.
- **upload** (object) - Details of the completed upload.
  - **id** (integer) - Unique identifier for the upload.
  - **product_id** (string) - Associated product ID.
  - **user_id** (integer) - ID of the user initiating the upload.
  - **original_filename** (string) - Original name of the file.
  - **mime_type** (string) - MIME type of the file.
  - **file_size** (integer) - Size of the file in bytes.
  - **file_path_original** (string) - Path to the original file in storage.
  - **file_path_preview** (string) - Path to the preview image (null if not generated).
  - **status** (string) - Current status of the upload (e.g., "pending_processing").
  - **storage_disk** (string) - The storage disk used (e.g., "s3").
  - **local_backup_path** (string) - Local backup path (null if not applicable).
  - **uploaded_to_s3_at** (string) - Timestamp of S3 upload.
  - **s3_upload_attempts** (integer) - Number of S3 upload attempts.
  - **preview** (string) - Preview information (null if not available).
  - **thumbnail** (string) - Thumbnail information (null if not available).
  - **created_at** (string) - Timestamp of creation.
  - **updated_at** (string) - Timestamp of last update.
  - **deleted_at** (string) - Timestamp of deletion (null if not deleted).

### Response Example
```json
{
  "message": "File uploaded to storage. Preview processing has started.",
  "upload": {
    "id": 101,
    "product_id": "85de3406-3c8c-42ef-b0a7-d99b3b7fc249",
    "user_id": 7,
    "original_filename": "photo.png",
    "mime_type": "image/png",
    "file_size": 335872,
    "file_path_original": "users/7/products/DbzK5gk8TwAK21gwct2GZF49r8qdIuYC",
    "file_path_preview": null,
    "status": "pending_processing",
    "storage_disk": "s3",
    "local_backup_path": null,
    "uploaded_to_s3_at": "2026-06-13T11:14:36.000000Z",
    "s3_upload_attempts": 0,
    "preview": null,
    "thumbnail": null,
    "created_at": "2026-06-13T11:13:42.000000Z",
    "updated_at": "2026-06-13T11:14:36.000000Z",
    "deleted_at": null
  }
}
```
```

--------------------------------

### List all galleries

Source: https://snapsell.org/docs/api

Lists all galleries associated with the user's API key. Supports pagination.

```APIDOC
## GET /api/external/v1/galleries

### Description
Lists all galleries for the authenticated user. Supports pagination.

### Method
GET

### Endpoint
/api/external/v1/galleries

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve (default is 1).
- **per_page** (integer) - Optional - The number of galleries to return per page (default is 30).
```

--------------------------------

### Add Uploads to Gallery

Source: https://snapsell.org/docs/api

Attach one or more completed uploads to a gallery using their upload IDs. Each upload can only be associated with a single gallery.

```bash
curl -sS -X POST "https://snapsell.org/api/external/v1/galleries/$GALLERY_HASH/items" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY_HERE" \
  -d "{\"upload_ids\": [$UPLOAD_ID]}"
```

--------------------------------

### List Galleries

Source: https://snapsell.org/docs/api

Retrieves a list of all galleries.

```APIDOC
## GET /galleries

### Description
Retrieves a list of all galleries.

### Method
GET

### Endpoint
/galleries
```

--------------------------------

### Complete Simple Upload

Source: https://snapsell.org/docs/api

Completes a simple file upload process.

```APIDOC
## POST /uploads/simple/{upload_id}/complete

### Description
Completes a simple file upload process.

### Method
POST

### Endpoint
/uploads/simple/{upload_id}/complete

### Parameters
#### Path Parameters
- **upload_id** (string) - Required - The ID of the upload.
```

--------------------------------

### Complete File Upload

Source: https://snapsell.org/docs/api

Call complete after uploading the file to S3 to finalize the upload process. The upload status will change to 'pending_processing', queuing preview generation.

```bash
curl -sS -X POST "https://snapsell.org/api/external/v1/uploads/simple/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer YOUR_KEY_HERE"
```

--------------------------------

### POST /api/external/v1/galleries/{gallery_hash}/items

Source: https://snapsell.org/docs/api

Attach one or more uploads to a gallery. Each upload can only belong to one gallery. Passing an upload that is already in a different gallery returns a 422 with the conflicting ids listed.

```APIDOC
## POST /api/external/v1/galleries/{gallery_hash}/items

### Description
Attach one or more uploads to a gallery. Each upload can only belong to one gallery — passing an upload that is already in a different gallery returns a **422** with the conflicting ids listed.

### Method
POST

### Endpoint
`https://snapsell.org/api/external/v1/galleries/{gallery_hash}/items`

### Parameters
#### Path Parameters
- **gallery_hash** (string) - Required - The hash of the gallery to which uploads will be attached.

#### Request Body
- **upload_ids** (array of integers) - Required - An array of 1–100 integers representing the `upload.id` values from a completed upload.

### Request Example
```json
{
  "upload_ids": [101, 102]
}
```

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message of successful attachment.
- **gallery** (object) - The updated gallery object including the newly attached uploads.
- **payment_url** (string) - The URL for payment if applicable.

#### Response Example (200 OK)
```json
{
  "message": "2 uploads added to gallery successfully.",
  "gallery": {
    "id": 42,
    "user_id": 7,
    "title": "Summer pack",
    "description": "Optional",
    "price": "9.99",
    "hash": "SEf4rXKf9y",
    "status": "active",
    "is_deleted": false,
    "is_collection": false,
    "is_adult_content": false,
    "views": 0,
    "created_at": "2026-06-13T11:07:46.000000Z",
    "updated_at": "2026-06-13T11:07:46.000000Z",
    "deleted_at": null,
    "uploads": [
      {
        "id": 101,
        "original_filename": "photo.png",
        "mime_type": "image/png",
        "file_size": 335872,
        "status": "processed",
        "pivot": { "gallery_id": 42, "upload_id": 101, "order": 0 }
      },
      {
        "id": 102,
        "original_filename": "video.mp4",
        "mime_type": "video/mp4",
        "file_size": 10485760,
        "status": "processed",
        "pivot": { "gallery_id": 42, "upload_id": 102, "order": 1 }
      }
    ]
  },
  "payment_url": "https://snapsell.org/buy/SEf4rXKf9y"
}
```

### Error Handling
#### Error — 409 Conflict
Returned if the file is not yet found on storage — ensure the S3 PUT returned 200 before calling complete.

#### Error — 422 (upload already in another gallery)
Returned if one or more uploads are already assigned to another gallery.

#### Response Example (422)
```json
{
  "message": "One or more uploads are already assigned to another gallery.",
  "conflicting_upload_ids": [102]
}
```
```

--------------------------------

### Upload a file - Complete

Source: https://snapsell.org/docs/api

Completes the file upload process after the file has been PUT to S3. This queues the file for processing.

```APIDOC
## POST /api/external/v1/uploads/simple/{upload_id}/complete

### Description
Completes the upload process for a given upload ID.

### Method
POST

### Endpoint
/api/external/v1/uploads/simple/{upload_id}/complete

### Parameters
#### Path Parameters
- **upload_id** (string) - Required - The ID of the upload to complete.

### Response
#### Success Response (200)
- **upload.status** (string) - The status of the upload, e.g., "pending_processing".
```

--------------------------------

### Add Item to Gallery

Source: https://snapsell.org/docs/api

Adds an item to a specific gallery.

```APIDOC
## POST /galleries/{gallery_hash}/items

### Description
Adds an item to a specific gallery.

### Method
POST

### Endpoint
/galleries/{gallery_hash}/items

### Parameters
#### Path Parameters
- **gallery_hash** (string) - Required - The unique hash of the gallery.
```

--------------------------------

### Sale Completed Webhook

Source: https://snapsell.org/docs/api

SnapSell sends a POST request to your configured webhook URL after a buyer successfully completes a purchase. This includes details about the transaction and is secured with a signature.

```APIDOC
## POST /webhook

### Description
This endpoint receives notifications when a sale is successfully completed in SnapSell.

### Method
POST

### Endpoint
Your configured webhook URL

### Headers
- **Content-Type**: `application/json`
- **X-SnapSell-Webhook-Timestamp** (string): Unix timestamp in seconds.
- **X-SnapSell-Webhook-Signature** (string): `v1=` + lowercase hex HMAC-SHA256 of `{timestamp}.{raw_body}`.
- **User-Agent** (string): `SnapSell-Webhooks/1.0`

### Request Body
- **id** (string) - Required - Unique identifier for the event.
- **type** (string) - Required - The type of event, e.g., `gallery.sale.completed`.
- **api_version** (string) - Required - The API version used for the event.
- **created_at** (string) - Required - Timestamp when the event was created.
- **data** (object) - Required - Contains the sale completion details.
  - **transaction_uuid** (string) - Required - Unique identifier for the transaction.
  - **gallery_id** (integer) - Required - The ID of the gallery where the sale occurred.
  - **gallery_hash** (string) - Required - A hash representing the gallery state.
  - **gallery_title** (string) - Required - The title of the gallery.
  - **amount** (string) - Required - The total amount of the sale.
  - **currency_code** (string) - Required - The currency used for the sale (e.g., EUR).
  - **seller_earning** (string) - Required - The amount the seller earns from the sale.
  - **buyer_email** (string) - Required - The email address of the buyer.
  - **payment_gateway** (string) - Required - The payment gateway used (e.g., stripe).
  - **completed_at** (string) - Required - Timestamp when the sale was completed.

### Request Example
```json
{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "type": "gallery.sale.completed",
  "api_version": "2026-04-07",
  "created_at": "2026-04-07T12:00:00+00:00",
  "data": {
    "transaction_uuid": "...",
    "gallery_id": 1,
    "gallery_hash": "...",
    "gallery_title": "...",
    "amount": "19.99",
    "currency_code": "EUR",
    "seller_earning": "17.50",
    "buyer_email": "buyer@example.com",
    "payment_gateway": "stripe",
    "completed_at": "2026-04-07T12:00:00+00:00"
  }
}
```

### Response
#### Success Response (200)
An empty response is expected upon successful receipt and processing of the webhook.

### Signature Verification
1. Read the raw request body before parsing it as JSON.
2. Extract the timestamp (`t`) from the `X-SnapSell-Webhook-Timestamp` header and the signature (`sig`) from the `X-SnapSell-Webhook-Signature` header (remove the `v1=` prefix).
3. Compute an HMAC-SHA256 hash of the string `{t}.{rawBody}` using your `webhook_signing_secret`.
4. Compare the computed hash (in lowercase hex) with the extracted `sig` using a constant-time comparison.
5. Optionally, check if the timestamp is within an acceptable window (e.g., ±5 minutes) to mitigate replay attacks.
```

--------------------------------

### Upload Response - 201 Created

Source: https://snapsell.org/docs/api

Response after initializing an upload. It provides a presigned S3 URL, the HTTP method (PUT), and necessary headers for uploading file bytes directly to S3. The upload ID is crucial for the completion step.

```json
{
  "message": "PUT the file bytes to the url using the provided headers, then call complete.",
  "upload": {
    "id": 101,
    "product_id": "472e30a4-111f-4274-87ee-f447ae635937",
    "user_id": 7,
    "original_filename": "photo.png",
    "mime_type": "image/png",
    "file_size": 335872,
    "file_path_original": "users/7/products/DLbsWD2IWwZdlF60AyDb8ZPaj55bwi8U",
    "file_path_preview": null,
    "status": "pending_direct_upload",
    "storage_disk": "s3",
    "local_backup_path": null,
    "uploaded_to_s3_at": null,
    "s3_upload_attempts": 0,
    "preview": null,
    "thumbnail": null,
    "created_at": "2026-06-13T11:24:59.000000Z",
    "updated_at": "2026-06-13T11:24:59.000000Z",
    "deleted_at": null
  },
  "url": "https://your-bucket.s3.region.amazonaws.com/users/7/products/DLbsWD2IWwZdlF60AyDb8ZPaj55bwi8U?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "method": "PUT",
  "headers": {
    "Content-Type": "image/png"
  }
}
```

--------------------------------

### Delete Gallery

Source: https://snapsell.org/docs/api

Delete a specific gallery using its hash. This action is irreversible.

```bash
curl -sS -X DELETE "https://snapsell.org/api/external/v1/galleries/GALLERY_HASH" \
  -H "Authorization: Bearer YOUR_KEY_HERE"
```

--------------------------------

### Add Uploads to Gallery Response (200 OK)

Source: https://snapsell.org/docs/api

A successful response when uploads are added to a gallery. It includes a confirmation message, details of the updated gallery, and a payment URL if applicable.

```json
{
  "message": "2 uploads added to gallery successfully.",
  "gallery": {
    "id": 42,
    "user_id": 7,
    "title": "Summer pack",
    "description": "Optional",
    "price": "9.99",
    "hash": "SEf4rXKf9y",
    "status": "active",
    "is_deleted": false,
    "is_collection": false,
    "is_adult_content": false,
    "views": 0,
    "created_at": "2026-06-13T11:07:46.000000Z",
    "updated_at": "2026-06-13T11:07:46.000000Z",
    "deleted_at": null,
    "uploads": [
      {
        "id": 101,
        "original_filename": "photo.png",
        "mime_type": "image/png",
        "file_size": 335872,
        "status": "processed",
        ...
        "pivot": { "gallery_id": 42, "upload_id": 101, "order": 0, ... }
      },
      {
        "id": 102,
        "original_filename": "video.mp4",
        "mime_type": "video/mp4",
        "file_size": 10485760,
        "status": "processed",
        ...
        "pivot": { "gallery_id": 42, "upload_id": 102, "order": 1, ... }
      }
    ]
  },
  "payment_url": "https://snapsell.org/buy/SEf4rXKf9y"
}
```

--------------------------------

### Complete File Upload

Source: https://snapsell.org/docs/api

Notifies the server that the file has been successfully uploaded to S3. This triggers verification of the file on storage and initiates preview generation. The upload ID is required for this step.

```json
{
  "message": "File uploaded to storage. Preview processing has started.",
  "upload": {
    "id": 101,
    "product_id": "85de3406-3c8c-42ef-b0a7-d99b3b7fc249",
    "user_id": 7,
    "original_filename": "photo.png",
    "mime_type": "image/png",
    "file_size": 335872,
    "file_path_original": "users/7/products/DbzK5gk8TwAK21gwct2GZF49r8qdIuYC",
    "file_path_preview": null,
    "status": "pending_processing",
    "storage_disk": "s3",
    "local_backup_path": null,
    "uploaded_to_s3_at": "2026-06-13T11:14:36.000000Z",
    "s3_upload_attempts": 0,
    "preview": null,
    "thumbnail": null,
    "created_at": "2026-06-13T11:13:42.000000Z",
    "updated_at": "2026-06-13T11:14:36.000000Z",
    "deleted_at": null
  }
}
```

--------------------------------

### Add uploads to the gallery

Source: https://snapsell.org/docs/api

Adds one or more completed uploads to a specific gallery. Each upload can only be associated with one gallery.

```APIDOC
## POST /api/external/v1/galleries/{gallery_hash}/items

### Description
Adds one or more upload IDs to a gallery.

### Method
POST

### Endpoint
/api/external/v1/galleries/{gallery_hash}/items

### Parameters
#### Path Parameters
- **gallery_hash** (string) - Required - The hash of the gallery to add items to.

#### Request Body
- **upload_ids** (array of strings) - Required - A list of upload IDs to add to the gallery.
```

--------------------------------

### Sale Webhook

Source: https://snapsell.org/docs/api

Receives a signed webhook notification when a gallery purchase is fulfilled.

```APIDOC
## POST your-url (Webhook)

### Description
Receives a signed webhook notification when a gallery purchase is fulfilled.

### Method
POST

### Endpoint
Your configured webhook URL
```

--------------------------------

### Add Uploads to Gallery Response (422 Conflict)

Source: https://snapsell.org/docs/api

This response is returned if one or more of the provided upload IDs are already associated with a different gallery. The conflicting IDs are listed.

```json
{
  "message": "One or more uploads are already assigned to another gallery.",
  "conflicting_upload_ids": [102]
}
```

--------------------------------

### DELETE /api/external/v1/galleries/{gallery_hash}

Source: https://snapsell.org/docs/api

Permanently delete a gallery. The attached uploads are not deleted and remain in your account, available to be added to a new gallery.

```APIDOC
## DELETE /api/external/v1/galleries/{gallery_hash}

### Description
Permanently delete a gallery. The attached uploads are not deleted — they remain in your account and can be added to a new gallery.

### Method
DELETE

### Endpoint
`https://snapsell.org/api/external/v1/galleries/{gallery_hash}`

### Parameters
#### Path Parameters
- **gallery_hash** (string) - Required - The hash of the gallery to be deleted.

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message of successful deletion.

#### Response Example (200 OK)
```json
{
  "message": "Gallery deleted successfully."
}
```
```

--------------------------------

### Delete a gallery

Source: https://snapsell.org/docs/api

Deletes a specific gallery. Use with caution as this action is irreversible.

```APIDOC
## DELETE /api/external/v1/galleries/{gallery_hash}

### Description
Deletes a specific gallery.

### Method
DELETE

### Endpoint
/api/external/v1/galleries/{gallery_hash}

### Parameters
#### Path Parameters
- **gallery_hash** (string) - Required - The hash of the gallery to delete.
```
Tokens:
Raw