# Gearment API integration

### Overview

Welcome to the Gearment Print-On-Demand (POD) Seller API!
This API enables seamless integration between your stores, applications, and the Gearment platform.
With our API, you can:

- Manage products and variants

- Sync inventory

- Create and manage orders

- Track fulfillment status

This documentation will guide you through authentication, rate limits, and how to start using the API.

> **Production API v3 URL:**
> https://apiv2.gearment.com/integration-handler
>
> **Sandbox API v3 URL:**
> https://api.gearmentinc.com/integration-handler

> **Need to use API v2**  
> 👉 [View API v2 Documentation here](https://api.gearment.com)

### Authentication

All API requests must be authenticated with an API Key. Unauthorized requests will be rejected.

**How to obtain your API Key**

1. Navigate to your **Team Settings** inside the Gearment platform.
2. Click on **Developer Settings**.
3. Request and generate your **API Key**.

> ⚠️ Important:
> Keep your API key secure. Do not share it publicly or embed it directly in client-side applications.
> If your API Key is compromised, immediately revoke it and generate a new one.

### Using API Key

Include your API key in the request headers:

> **X-Gearment-Client-Key**: Your_Gearment_Client_Key
>
> **X-Gearment-Client-Secret**: Your_Gearment_Client_Secret"

### Rate Limiting

To ensure stable service for all users, the Gearment API enforces rate limiting.

| Rate Limit Type  | Value |
| ------------- |-------------|
| Requests      | 100 requests per 10 seconds, Block for 1 minute     |
| Retry-After   | If exceeded, Retry-After header will indicate when you can retry     |

If you exceed the rate limit, the API will respond with:

```bash
json{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Please retry later."
  }
}
```

**Best Practices:**

- Implement exponential backoff retries for 429 errors.
- Monitor your API usage.
- Optimize your integrations to avoid unnecessary requests (e.g., batch updates when possible).

### Migration Guide

**🚀 Migration Guide: Moving from [v1/v2](https://api.gearment.com) to [Next App v3 API/Webhook](https://developers.gearment.com/)**

We’ve upgraded our platform to the new [**Next App**](https://dash.gearment.com), which provides [**API v3**](https://developers.gearment.com/), delivering better performance, scalability, and new features.  

Good news:  
✅ **Backward compatibility is preserved.**  
Your existing integrations using [**API v1/v2**](https://api.gearment.com) and **Webhook v1/v2** will continue to work **out of the box** without changes.  
✅ You can switch to the new APIs at your own pace.  

---

**1. What stays the same**
- Your current API calls [**v1/v2**](https://api.gearment.com) and boundWebhooks will continue to work exactly as before.  
- We have a **compatibility layer** that routes those calls to the new system.  
- **No immediate action is required** for existing apps.  

---

**2. API Endpoints Overview**

| Version | Base URL | Sandbox | Notes |
|---------|----------|---------|-------|
| v1/v2   | `https://api.gearment.com` | N/A | v1/v2 API, still supported via compatibility layer |
| v3      | `https://apiv2.gearment.com/integration-handler` | `https://api.gearmentinc.com/integration-handler` | Next App API (new API features) |

---

**3. What’s new in [API v3](https://developers.gearment.com/)**
- Modernized endpoints for improved queries and faster responses.  
- Consistent authentication and more detailed error handling.  
- Access to **new features** and data models not available in v1/v2.  
- Enhanced developer experience with updated documentation and examples.  

**Example API v3 Request:**
- Now you can filter product variants with more criterions, e.g.: look for product variants have product_id G5000, variant_id in GM0002003147/GM0002005986, with size 3XL, and color Daisy.
```curl
curl -i -X GET \
  -H "X-Gearment-Client-Key: xxx" \
  -H "X-Gearment-Client-Secret: xxxxxx" \
  'https://apiv2.gearment.com/integration-handler/api/v3/catalog/variants/stock?filter.product_ids=G5000&filter.variant_ids=GM0002003147&filter.variant_id=GM0002005986&filter.sizes=3XL&filter.color_codes=daisy&filter.stock_labels=VENDOR_CATALOG_VARIANT_STOCK_LABEL_IN_STOCK&paging.page=1&paging.limit=100'
```

- You can also list/delete webhooks via [APIs](https://developers.gearment.com/api/api.webhook.v1.vendorwebhookapi).

---

**4. Webhooks in v3**
Modified payload for webhooks

👉 Configure your webhooks in the [Developer Settings](https://dash.gearment.com/pod/teams/developer-settings/webhooks).  

**Example Shipping Address Verified Webhook Payload:**
- v1/v2:
```json
{
  "type": "shipping_address_verified",
  "data": {
    "gearment_ord_id": "ORD123456789",
    "gearment_ord_name": "#10001",
    "ord_status": "pending",
    "verify_address": "verified",
    "order_id": "EXT-1234567"
  }
}
```

- v3:
```json
{
  "type": "shipping_address_verified",
  "order": {
    "gearment_id": "ORD123456789",
    "gearment_name": "#10001",
    "vendor_id": "EXT-1234567",
    "verify_address": "verified",
    "ord_status": "pending"
  }
}
```

---

**5. Migration Path**
If you’re ready to explore [**API v3**](https://developers.gearment.com/), follow these steps:  

1. Take a glance at our **API v3 Documentation**: [👉 Get Started Here](https://developers.gearment.com/)  
2. Visit [Developer Settings](https://dash.gearment.com/pod/teams/developer-settings/api-credentials) to generate new API credentials for [API/Webhooks v3](https://developers.gearment.com/).  
3. Review the updated endpoint list and request/response formats.  
4. Update your integration to start using v3 endpoints at your own pace.  

---

**6. Recommendations**
- **Short-term:** Continue running on v1/v2 without changes if everything works.  
- **Medium-term:** Start adopting v3 for new development to take advantage of improvements.  
- **Long-term:** Plan a full migration, as v1/v2 may be deprecated in the future *(deprecation timelines will be communicated well in advance).*  

---

**7. Support**
Need help migrating?  
- 📖 [Documentation](https://developers.gearment.com/)  
- 💬 [Contact our support team](mailto:integration@gearment.com)  

Version: v3.0.0

## Servers

Production Server
```
https://apiv2.gearment.com/integration-handler
```

Sandbox Server
```
https://api.gearmentinc.com/integration-handler
```

## Security

### ApiKeyAuth

Type: apiKey
In: header
Name: X-API-Key

### BearerAuth

Type: http
In: header
Name: Authorization
Scheme: bearer
Bearer Format: JWT

### CookieAuth

Type: apiKey
In: cookie
Name: accessToken
Scheme: bearer

## Download OpenAPI description

[Gearment API integration](https://developers.gearment.com/_bundle/api.yaml)

## Webhook

VendorWebhookAPI provides webhook management for real-time event notifications.
 Register webhooks to receive automated notifications when orders are completed, cancelled, or tracking is updated.

 Base URL: https://apiv2.gearment.com/integration-handler
 Authentication: API Key (header: X-API-Key, X-API-Secret)

### List Webhook

 - [GET /api/v3/webhooks](https://developers.gearment.com/api/api.webhook.v1.vendorwebhookapi/api.webhook.v1.vendorwebhookapi.vendorlistwebhook.md): List all registered webhooks

 GET /api/v3/webhooks

 Returns:
   - All registered webhooks for your account
   - Webhook status (active/inactive)
   - Event topics subscribed
   - Delivery URLs

 Use cases:
   - Audit webhook configurations
   - Verify webhook setup
   - List active event subscriptions

### Create Webhook

 - [POST /api/v3/webhooks](https://developers.gearment.com/api/api.webhook.v1.vendorwebhookapi/api.webhook.v1.vendorwebhookapi.vendorcreatewebhook.md): Register a new webhook for event notifications

 POST /api/v3/webhooks
 Content-Type: application/json

 Available topics:
   - VENDOR_WEBHOOK_TOPIC_ORDER_COMPLETED: Order fulfillment completed
   - VENDOR_WEBHOOK_TOPIC_ORDER_CANCELED: Order was cancelled
   - VENDOR_WEBHOOK_TOPIC_TRACKING_UPDATED: Shipping tracking updated
   - VENDOR_WEBHOOK_TOPIC_ADDRESS_UNVERIFIED: Shipping address validation failed

 Security:
   - Webhooks are sent via HTTPS POST
   - Include signature header for verification
   - Must respond with 200 OK within 30 seconds

 Use cases:
   - Automate order status updates
   - Sync tracking information
   - Alert customers of shipment

### Delete Webhook

 - [DELETE /api/v3/webhooks/{webhook_id}](https://developers.gearment.com/api/api.webhook.v1.vendorwebhookapi/api.webhook.v1.vendorwebhookapi.vendordeletewebhook.md): Delete a webhook subscription

 DELETE /api/v3/webhooks/{webhook_id}

 Use cases:
   - Remove unused webhooks
   - Update webhook configuration (delete + recreate)

## Order

VendorOrderAPI provides comprehensive order management capabilities for vendors.
 All endpoints require authentication via X-API-Key and X-API-Secret headers.

 Base URL: https://apiv2.gearment.com/integration-handler
 Authentication: API Key (header: X-API-Key, X-API-Secret)

### List Order

 - [GET /api/v3/orders](https://developers.gearment.com/api/api.order.v1.vendororderapi/api.order.v1.vendororderapi.vendorlistorder.md): List orders with filtering and pagination

 GET /api/v3/orders

 Use cases:
   - Monitor order status changes
   - Sync orders to your system
   - Generate reports on order volumes

### List Order Draft

 - [GET /api/v3/orders/draft](https://developers.gearment.com/api/api.order.v1.vendororderapi/api.order.v1.vendororderapi.vendorlistorderdraft.md): List order drafts (pending checkout)

 GET /api/v3/orders/draft

 Use cases:
   - Review drafts before checkout
   - Identify stuck/incomplete orders

### Create Order Draft

 - [POST /api/v3/orders/draft](https://developers.gearment.com/api/api.order.v1.vendororderapi/api.order.v1.vendororderapi.vendorcreateorderdraft.md): Create a new order draft

 POST /api/v3/orders/draft
 Content-Type: application/json

 Use cases:
   - Place new orders programmatically
   - Bulk order creation
   - Integration with e-commerce platforms

### Create Order Draft With Label

 - [POST /api/v3/orders/draft/labeled](https://developers.gearment.com/api/api.order.v1.vendororderapi/api.order.v1.vendororderapi.vendorcreateorderdraftwithlabel.md): Create order draft with pre-purchased shipping label

 POST /api/v3/orders/draft/labeled
 Content-Type: application/json

 Use cases:
   - Use your own shipping account
   - Consolidate shipping management

### Update Order Draft Line Items

 - [PATCH /api/v3/orders/draft/line-items](https://developers.gearment.com/api/api.order.v1.vendororderapi/api.order.v1.vendororderapi.vendorupdateorderdraftlineitems.md): Update line items in an order draft

 PATCH /api/v3/orders/draft/line-items
 Content-Type: application/json

 Use cases:
   - Update quantities before checkout
   - Change designs on line items
   - Fix errors in draft orders

### Get Order Draft

 - [GET /api/v3/orders/draft/{order_id}](https://developers.gearment.com/api/api.order.v1.vendororderapi/api.order.v1.vendororderapi.vendorgetorderdraft.md): Get details of a specific order draft

 GET /api/v3/orders/draft/{order_id}

 Use cases:
   - Review draft before checkout
   - Verify pricing and line items

### Get Price Quote

 - [POST /api/v3/orders/price](https://developers.gearment.com/api/api.order.v1.vendororderapi/api.order.v1.vendororderapi.vendorgetpricequote.md): Get price quote before creating order

 POST /api/v3/orders/price
 Content-Type: application/json

 Response includes:
   - order_total: Total cost
   - order_subtotal: Product costs
   - order_shipping_fee: Shipping cost
   - order_tax: Tax amount

 Use cases:
   - Show pricing to customers before checkout
   - Compare shipping methods
   - Calculate profit margins

### Get Order

 - [GET /api/v3/orders/{order_id}](https://developers.gearment.com/api/api.order.v1.vendororderapi/api.order.v1.vendororderapi.vendorgetorder.md): Get details of a specific order

 GET /api/v3/orders/{order_id}

 Response includes:
   - Order status and tracking
   - Line items with printing details
   - Shipping information
   - Payment/transaction details

 Use cases:
   - Track order fulfillment
   - Get shipping/tracking info
   - Customer support queries

## Catalog

VendorCatalogAPI provides access to product catalog and inventory management.
 Use these endpoints to browse available products, check stock status, and get product details.

 Base URL: https://apiv2.gearment.com/integration-handler
 Authentication: API Key (header: X-API-Key, X-API-Secret)

### List Catalog

 - [GET /api/v3/catalog](https://developers.gearment.com/api/api.catalog.v1.vendorcatalogapi/api.catalog.v1.vendorcatalogapi.vendorlistcatalog.md): List all available products in the catalog

 GET /api/v3/catalog

 Returns:
   - Product listings with base information
   - Available variants for each product
   - Pricing and printing options

 Use cases:
   - Build product catalog in your system
   - Display available products to customers
   - Sync product updates

### List Catalog Variant

 - [GET /api/v3/catalog/variants](https://developers.gearment.com/api/api.catalog.v1.vendorcatalogapi/api.catalog.v1.vendorcatalogapi.vendorlistcatalogvariant.md): List product variants with detailed specifications

 GET /api/v3/catalog/variants

 Returns:
   - Variant details (size, color, SKU)
   - Pricing information
   - Stock availability
   - Print area specifications

 Use cases:
   - Get variant-specific pricing
   - Check size/color availability
   - Display product options to customers

### Get Catalog Stock Status

 - [GET /api/v3/catalog/variants/stock](https://developers.gearment.com/api/api.catalog.v1.vendorcatalogapi/api.catalog.v1.vendorcatalogapi.vendorgetcatalogstockstatus.md): Check real-time stock status for variants

 GET /api/v3/catalog/variants/stock

 Returns:
   - Stock status: in_stock, out_of_stock, discontinued, temporarily_unavailable
   - Expected restock date (if applicable)

 Use cases:
   - Verify stock before order placement
   - Update product availability in your system
   - Show stock status to customers