Extra APIs

Overview

The Extra APIs provide additional functionality beyond the standard PromoStandards services. These APIs offer enhanced product data, supplier information, inventory management, and other features that complement your PromoStandards integration.

What’s Included

Products - Rich product data with pricing, variants, and classifications
Suppliers - Supplier directory with capabilities and metadata
Brands - Brand information organized by supplier
Categories - Product categorization for organization and filtering
Inventory - Cached inventory data with efficient querying
Decorations - Decoration options and pricing by supplier
Part ID Mappings - Cross-reference part IDs across different services

API Versions

Extra APIs are available in two versions:

Version	Base Path	Response Format	Status
V1	`/extra/v1`	snake_case	Stable
V2	`/extra/v2`	camelCase	Recommended

Recommendation: Use V2 endpoints for new integrations. V2 provides consistent pagination, camelCase responses, and additional features.

Authentication

All Extra API endpoints require authentication.

API Key:

X-API-Key: your-api-key-here

Bearer Token:

Authorization: Bearer your-token-here

Pagination

V2 endpoints use consistent pagination with the following parameters and response format:

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`page_size`	integer	20	Items per page (max varies by endpoint)

Response Format:

{
  "count": 150,
  "page": 1,
  "pageSize": 20,
  "totalPages": 8,
  "next": "https://api.psrestful.com/extra/v2/products?page=2",
  "previous": null,
  "results": [...]
}

Products API

List Products

Get a paginated list of products with optional filtering.

V2 Endpoint:

GET /extra/v2/products

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number
`page_size`	integer	Items per page
`supplier_code`	string	Filter by supplier (e.g., SanMar, HIT)
`brand`	string	Filter by brand name
`category`	string	Filter by category
`search`	string	Search in product name/description

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/products?supplier_code=SanMar&page_size=10" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "count": 5420,
  "page": 1,
  "pageSize": 10,
  "totalPages": 542,
  "next": "https://api.psrestful.com/extra/v2/products?supplier_code=SanMar&page=2&page_size=10",
  "previous": null,
  "results": [
    {
      "extraId": 12345,
      "productId": "PC61",
      "supplierCode": "SanMar",
      "name": "Port & Company Essential Tee",
      "description": "A wardrobe essential...",
      "imageUrl": "https://...",
      "listPrice": 5.98,
      "currency": "USD"
    }
  ]
}

Get Product Details

Get detailed product information with optional data expansions.

V2 Endpoint:

GET /extra/v2/products/{product_id}

Path Parameters:

Parameter	Type	Description
`product_id`	string	Product ID or Extra ID

Query Parameters:

Parameter	Type	Description
`expand`	string	Comma-separated expansions: `ppcs`, `inventory`, `media`
`shop`	string	Shopify shop domain (for shop-specific pricing)
`currency`	string	Currency code: `USD` or `CAD`
`country`	string	Country code for localized data
`language`	string	Language code

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/products/PC61?expand=ppcs,inventory&currency=USD" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "extraId": 12345,
  "productId": "PC61",
  "supplierCode": "SanMar",
  "name": "Port & Company Essential Tee",
  "description": "A wardrobe essential that icons are made of...",
  "brand": "Port & Company",
  "categories": ["Apparel", "T-Shirts"],
  "imageUrl": "https://...",
  "images": [...],
  "colors": [...],
  "sizes": [...],
  "parts": [...],
  "combinedPpc": {...},
  "inventory": [...]
}

Get Product PPCs (Pricing)

Get combined pricing data including list price, net price, and customer-specific pricing.

V2 Endpoint:

GET /extra/v2/products/{product_id}/ppcs

Query Parameters:

Parameter	Type	Default	Description
`currency`	string	USD	Currency: `USD` or `CAD`
`fob_point_id`	string	-	Specific FOB point for shipping calculations

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/products/PC61/ppcs?currency=USD" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "productId": "PC61",
  "currency": "USD",
  "fobPoints": [...],
  "priceBreaks": [
    {
      "minQuantity": 1,
      "maxQuantity": 11,
      "listPrice": 5.98,
      "netPrice": 4.18,
      "customerPrice": 3.95
    },
    {
      "minQuantity": 12,
      "maxQuantity": 35,
      "listPrice": 5.48,
      "netPrice": 3.84,
      "customerPrice": 3.65
    }
  ],
  "decorationPricing": [...]
}

Get Product Metafields

Get product identifiers (extra_id, supplier_code, product_id) by extra IDs.

V2 Endpoint:

GET /extra/v2/products/metafields

Query Parameters:

Parameter	Type	Description
`extra_id`	string	Comma-separated list of extra IDs
`page`	integer	Page number
`page_size`	integer	Items per page

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/products/metafields?extra_id=12345,12346,12347" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "count": 3,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1,
  "results": [
    {
      "extraId": 12345,
      "supplierCode": "SanMar",
      "productId": "PC61"
    },
    {
      "extraId": 12346,
      "supplierCode": "SanMar",
      "productId": "PC54"
    }
  ]
}

Get Extra ID by Product

Look up the extra ID for a product given supplier code and product ID.

V2 Endpoint:

GET /extra/v2/products/get-extra-id/

Query Parameters:

Parameter	Type	Required	Description
`supplier_code`	string	Yes	Supplier code
`product_id`	string	Yes	Product ID

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/products/get-extra-id/?supplier_code=SanMar&product_id=PC61" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "extraId": 12345,
  "supplierCode": "SanMar",
  "productId": "PC61"
}

Get Product by Title

Look up product metafields by supplier code and product title.

V2 Endpoint:

GET /extra/v2/products/get-metafields-by-title/

Query Parameters:

Parameter	Type	Required	Description
`supplier_code`	string	Yes	Supplier code
`title`	string	Yes	Product title to search

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/products/get-metafields-by-title/?supplier_code=SanMar&title=Essential%20Tee" \
  -H "X-API-Key: your-api-key"

Get Top-Selling Variants (V1)

Get product variants sorted by sales volume.

V1 Endpoint:

GET /extra/v1/products/{product_id}/sorted-parts

Query Parameters:

Parameter	Type	Default	Description
`days`	integer	30	Lookback period in days

Example Request:

curl -X GET "https://api.psrestful.com/extra/v1/products/PC61/sorted-parts?days=90" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "count": 45,
  "parts": [
    {
      "partId": "PC61-BLK-S",
      "color": "Black",
      "size": "S",
      "totalSales": 1250
    },
    {
      "partId": "PC61-BLK-M",
      "color": "Black",
      "size": "M",
      "totalSales": 1180
    }
  ]
}

Get Product Classifications (V1)

Get product classifications for various platforms (Shopify, Google, Amazon, Avalara, TaxJar).

V1 Endpoint:

GET /extra/v1/products/{extra_id}/classifications

Example Request:

curl -X GET "https://api.psrestful.com/extra/v1/products/12345/classifications" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "id": 12345,
  "name": "Port & Company Essential Tee",
  "listPrice": 5.98,
  "shopify": {
    "productType": "T-Shirts",
    "tags": ["apparel", "t-shirt", "cotton"]
  },
  "google": {
    "category": "Apparel & Accessories > Clothing > Shirts & Tops"
  },
  "amazon": {
    "category": "Clothing, Shoes & Jewelry > Men > Clothing > Shirts > T-Shirts"
  },
  "avalara": {
    "taxCode": "PC040100"
  },
  "taxjar": {
    "taxCode": "20010"
  }
}

Suppliers API

List Suppliers

Get a paginated list of suppliers with optional filtering.

V2 Endpoint:

GET /extra/v2/suppliers

Query Parameters:

Parameter	Type	Description
`shopify_ready`	boolean	Filter suppliers ready for Shopify integration
`credentials_available`	boolean	Filter suppliers with available credentials
`decorations_available`	boolean	Filter suppliers with decoration data
`page`	integer	Page number
`page_size`	integer	Items per page

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/suppliers?shopify_ready=true&page_size=50" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "count": 85,
  "page": 1,
  "pageSize": 50,
  "totalPages": 2,
  "next": "https://api.psrestful.com/extra/v2/suppliers?shopify_ready=true&page=2&page_size=50",
  "previous": null,
  "results": [
    {
      "id": 1,
      "code": "SanMar",
      "name": "SanMar",
      "website": "https://www.sanmar.com",
      "shopifyReady": true,
      "credentialsAvailable": true,
      "decorationsAvailable": true,
      "supported": true
    }
  ]
}

Brands API

List Brands

Get brands, optionally filtered by supplier.

V2 Endpoint:

GET /extra/v2/brands

Query Parameters:

Parameter	Type	Description
`supplier_id`	integer	Filter by supplier ID
`supplier_code`	string	Filter by supplier code
`page`	integer	Page number
`page_size`	integer	Items per page

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/brands?supplier_code=SanMar" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "count": 45,
  "page": 1,
  "pageSize": 20,
  "totalPages": 3,
  "results": [
    {
      "id": 101,
      "name": "Port & Company",
      "supplierCode": "SanMar"
    },
    {
      "id": 102,
      "name": "Nike",
      "supplierCode": "SanMar"
    }
  ]
}

Categories API

Get product categories, optionally filtered by supplier.

V2 Endpoint:

GET /extra/v2/categories

Query Parameters:

Parameter	Type	Description
`supplier_id`	integer	Filter by supplier ID
`supplier_code`	string	Filter by supplier code
`page`	integer	Page number
`page_size`	integer	Items per page

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/categories?supplier_code=SanMar" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "count": 28,
  "page": 1,
  "pageSize": 20,
  "totalPages": 2,
  "results": [
    {
      "id": 1,
      "name": "T-Shirts",
      "supplierCode": "SanMar"
    },
    {
      "id": 2,
      "name": "Polos",
      "supplierCode": "SanMar"
    }
  ]
}

Inventory API

List Inventory

Get cached inventory data for a supplier with efficient filtering.

V2 Endpoint:

GET /extra/v2/inventory/{supplier_code}

Path Parameters:

Parameter	Type	Description
`supplier_code`	string	Supplier code (e.g., SanMar)

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number
`page_size`	integer	Items per page
`product_id`	string	Filter by product ID
`part_id`	string	Filter by part ID
`last_modified__since`	string	Filter by modification time (e.g., `1h`, `30m`, `2d`, `7d`)

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/inventory/SanMar?product_id=PC61&page_size=100" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "count": 245,
  "page": 1,
  "pageSize": 100,
  "totalPages": 3,
  "results": [
    {
      "productId": "PC61",
      "partId": "PC61-BLK-S",
      "quantityAvailable": 15420,
      "warehouseId": "WH001",
      "warehouseName": "Dallas, TX",
      "lastModified": "2025-01-16T10:30:00Z"
    }
  ]
}

Time Filter Formats:

Format	Example	Description
Minutes	`30m`	Last 30 minutes
Hours	`1h`, `24h`	Last N hours
Days	`2d`, `7d`	Last N days

Decorations API

Get Supplier Decorations

Get available decoration methods and pricing for a supplier.

V2 Endpoint:

GET /extra/v2/suppliers/{supplier_code}/decorations

Path Parameters:

Parameter	Type	Description
`supplier_code`	string	Supplier code

Query Parameters:

Parameter	Type	Default	Description
`currency`	string	USD	Currency: `USD` or `CAD`

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/suppliers/SanMar/decorations?currency=USD" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "count": 12,
  "results": [
    {
      "id": 1,
      "name": "Screen Print",
      "description": "Traditional screen printing",
      "priceBreaks": [
        {
          "minQuantity": 1,
          "maxQuantity": 11,
          "price": 3.50,
          "setupFee": 25.00
        },
        {
          "minQuantity": 12,
          "maxQuantity": 47,
          "price": 2.75,
          "setupFee": 25.00
        }
      ],
      "locations": ["Front", "Back", "Left Sleeve", "Right Sleeve"]
    },
    {
      "id": 2,
      "name": "Embroidery",
      "description": "Machine embroidery",
      "pricePerStitch": 0.0015,
      "minimumCharge": 5.00,
      "locations": ["Left Chest", "Right Chest", "Cap Front"]
    }
  ]
}

Part ID Mappings API

Get Part ID Mappings

Get cross-reference mappings between part IDs used in different PromoStandards services (Media, Inventory, PPC).

V2 Endpoint:

GET /extra/v2/part-id-mappings

Query Parameters:

Parameter	Type	Description
`supplier`	integer	Filter by supplier ID
`supplier_code`	string	Filter by supplier code
`product_id`	string	Filter by product ID
`page`	integer	Page number
`page_size`	integer	Items per page

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/part-id-mappings?supplier_code=SanMar&product_id=PC61" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "count": 45,
  "page": 1,
  "pageSize": 20,
  "totalPages": 3,
  "results": [
    {
      "productId": "PC61",
      "medId": "PC61-BLK-S",
      "invId": "PC61BLKS",
      "ppcId": "PC61-BLK-S"
    },
    {
      "productId": "PC61",
      "medId": "PC61-BLK-M",
      "invId": "PC61BLKM",
      "ppcId": "PC61-BLK-M"
    }
  ]
}

Use Case: Different PromoStandards services sometimes use different part ID formats. This endpoint helps you map between them when correlating data across services.

Web Scraper API (V1)

Scrape Product Data

Scrape additional product data from supplier websites.

V1 Endpoint:

GET /extra/v1/scrape/{supplier_code}/

Path Parameters:

Parameter	Type	Description
`supplier_code`	string	Supplier code

Query Parameters:

Parameter	Type	Required	Description
`url`	string	Yes	Product URL to scrape (must be valid HTTP URL)

Example Request:

curl -X GET "https://api.psrestful.com/extra/v1/scrape/SanMar/?url=https://www.sanmar.com/p/PC61" \
  -H "X-API-Key: your-api-key"

Response: 200 OK

{
  "pmsMatch": true,
  "height": 2.5,
  "width": 12.0,
  "casePack": 72,
  "caseWeight": 18.5,
  "masterCarton": {
    "quantity": 144,
    "price": 5.25,
    "weight": 38.0
  },
  "openingDiameter": null
}

Note: This endpoint is useful for obtaining packaging and dimension data not available through standard PromoStandards services.

Error Handling

Error Response Format

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes

Code	Meaning	Common Causes
`200`	OK	Request succeeded
`400`	Bad Request	Invalid parameters
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource not found
`429`	Too Many Requests	Rate limit exceeded

Best Practices

1. Use V2 Endpoints

V2 endpoints provide consistent pagination, camelCase responses, and additional features. Use V1 only for features not yet available in V2.

2. Paginate Large Requests

Always use pagination for list endpoints. Start with reasonable page sizes (20-50) and implement proper pagination handling.

3. Use Filters Efficiently

Filter data at the API level rather than fetching everything and filtering client-side. This reduces bandwidth and improves performance.

4. Cache Responses Appropriately

Products/Suppliers/Brands/Categories: Cache for hours or days (changes infrequently)
Inventory: Cache briefly or use last_modified__since filter
Pricing: Cache with appropriate TTL based on your business needs

5. Use Expand Parameter Wisely

Only request expanded data when needed. Fetching ppcs and inventory adds processing time.

Credentials API - Configure supplier credentials for customer-specific pricing
Sub-Accounts API - Manage multi-tenant access
Authentication - API authentication methods
Rate Limits - API usage limits

Support

For additional help:

Email: devs@psrestful.com

Last Updated: January 2025 API Version: v1, v2

Sub-Accounts API PSMEDx API

Extra APIs

Overview

What’s Included

API Versions

Authentication

Pagination

Products API

List Products

Get Product Details

Get Product PPCs (Pricing)

Get Product Metafields

Get Extra ID by Product

Get Product by Title

Get Top-Selling Variants (V1)

Get Product Classifications (V1)

Suppliers API

List Suppliers

Brands API

List Brands

Categories API

List Categories

Inventory API

List Inventory

Decorations API

Get Supplier Decorations

Part ID Mappings API

Get Part ID Mappings

Web Scraper API (V1)

Scrape Product Data

Error Handling

Error Response Format

HTTP Status Codes

Best Practices

1. Use V2 Endpoints

2. Paginate Large Requests

3. Use Filters Efficiently

4. Cache Responses Appropriately

5. Use Expand Parameter Wisely

Related Documentation

Support