Auth & Environment

• Auth: OAuth 2.0 (client credentials) yielding short-lived access tokens.
• Environments: Sandbox (test) and Production; keep shipper numbers & account IDs separate.
• Scope: Enable only the products you need (Rate, Ship, Track) to avoid permission errors.

Core Capabilities

• Rates by service (e.g., Ground, 2nd Day Air), including negotiated rates.
• Shipment creation with label formats (PDF, ZPL/EPL) and return labels.
• Tracking lookups (single or batch) with status milestones.
• Address validation & classification (residential vs. commercial).

Typical Flow

1. Validate/normalize address.
2. Get rates (dim weight, declared value, special services).
3. Create the shipment → receive label + tracking number.
4. (Optional) Schedule a pickup; store tracking events.

Common Gotchas

• Dimensional weight rules affect cost—always send accurate dimensions.
• International shipments require customs docs (HS codes, reason for export).
• Label format must match your printer (ZPL for thermal, PDF for laser).
• Residential/commercial misclassification can change rates/surcharges.

Auth & Setup

• Auth: OAuth 2.0 client credentials → access token.
• Account: Ensure shipping services are enabled on the account you’ll bill.
• Labels: PDF & ZPL/EPL; support for returns and paperless trade where applicable.

Key Endpoints

• Rates: quote services, add options (signature, Saturday delivery).
• Ship: create, cancel, and return shipments.
• Track: detailed scan events, proof-of-delivery where permitted.
• Pickup: schedule/cancel pickups; cutoff/business days logic.

Auth & Access

• Credential: Web Tools USERID (and sometimes password) assigned per account.
• Usage: Legacy XML over HTTP; some newer endpoints offer REST. IP whitelisting may apply.

What You Can Do

• Rates: USPS retail/commercial pricing for supported services.
• Tracking: basic scan events by tracking number.
• Address checks: ZIP lookup, City/State, and standardization.
• Labels: typically via eVS/PC-Postage rather than public XML API.

Auth Layers

• LWA: Exchange refresh token → access token for the selling partner’s account.
• AWS SigV4: Sign each HTTP request (region & service specific).
• RDT: Restricted Data Tokens for PII fields (e.g., buyer info).

Key Domains

• Orders: list/get orders & line items; acknowledge, ship, confirm.
• Catalog & Listings: list catalogs, create/update offers & prices.
• Feeds/Uploads: bulk operations (inventory, pricing, listings).
• Reports: schedule & download; flat files and JSON.

Operational Advice

• Abstract marketplace IDs and currencies; avoid hard-coding NA/EU regions.
• Centralize signing; verify system clock skew to prevent SigV4 failures.
• Log original payloads and responses to reconcile with Seller Central.

Security

• Scope approvals are audited; store tokens securely.
• Use RDT only when necessary; purge PII promptly per policy.

Auth & Scopes

• Per-store OAuth install → Admin API access token.
• Least-privilege scopes (e.g., write_products, read_orders).
• Webhook HMAC validation using the app’s shared secret.

What You Can Do

• Products/Variants: CRUD, images, metafields.
• Orders/Fulfillment: read/update, create fulfillments & tracking.
• Pricing: discounts, price rules, draft orders.
• Storefront: via Storefront GraphQL for headless builds.

Fulfillment Flow (Typical)

1. Order created → webhook (orders/create).
2. Rate shop cart at checkout via carrier APIs or a shipping app.
3. Create fulfillment with tracking; update order status.
4. Webhook (fulfillments/create) → notify customer.

Metafields & Extensibility

• Attach custom data to products, orders, customers.
• Use Admin UI extensions & app blocks for merchant-facing UI.

Auth & Setup

• Auth: OAuth 2.0 with merchant-granted tokens.
• Scopes: Fine-grained (e.g., merchant:read, inventory:write).
• Environment: Sandbox (developer) and Production (merchant live data).

Core Capabilities

• Process payments (credit, debit, contactless).
• Access order lifecycle (create, update, close orders).
• Manage inventory (items, modifiers, stock counts).
• Customer profiles (loyalty, marketing integration).
• Webhooks for payments, orders, employee activity.

Typical Flow

1. App installed → OAuth authorization → get merchant token.
2. Create or update an order via API.
3. Process payment → receive confirmation with IDs.
4. Subscribe to webhooks for payment/order updates.

Common Gotchas

• Access tokens are merchant-specific; don’t reuse across merchants.
• Webhooks must validate Clover’s HMAC signature.
• Sandbox may not support all card features (test carefully).
• Some endpoints differ slightly by device type (Flex, Mini, Station).

Auth & Permissions

• OAuth 2.0 → user access token → exchange for long-lived token → page access token.
• Common permissions: pages_manage_posts, pages_read_engagement, pages_manage_metadata, instagram_basic, instagram_content_publish (IG).
• App Review required for most publish/read scopes beyond development mode.

Core Capabilities

• Publish content to Facebook Pages & Instagram Business accounts.
• Read insights/engagement, manage comments, DMs (IG permissions required).
• Webhooks for subscriptions (e.g., comments, mentions, messages).

Typical Flow

1. User logs in → get user token → exchange long-lived token.
2. Retrieve Page list → request Page Access Token.
3. Publish posts or media; subscribe to webhooks for comments/messages.
4. Refresh tokens periodically; rotate app secret.

Gotchas

• Development mode limits data to app roles until App Review approval.
• Different endpoints/permissions for Instagram vs Facebook Pages.
• Rate limits & feature limits vary; handle errors with backoff.

Auth & Scopes

• OAuth 2.0 Authorization Code → access/refresh tokens.
• Common scopes: r_liteprofile, w_member_social, rw_organization_admin, r_organization_social.
• Organization posting requires admin privileges for the organization.

Core Capabilities

• Create UGC posts (member or organization actor).
• Upload and attach images/videos to posts.
• Analytics and social actions (likes, comments) with proper scopes.

Typical Flow

1. OAuth login → verify org admin permissions.
2. (Optional) Register and upload media, capture asset URNs.
3. Create UGC post with org actor; monitor engagement.
4. Use paging for analytics; respect throttling headers.

Gotchas

• Many APIs require partner application and approval.
• UGC vs Shares APIs differ; prefer UGC for newer features.
• Webhooks/notifications are limited—plan for polling in some cases.

Auth & Access

• OAuth 2.0 with app-configured redirect URIs.
• Scopes vary by product (e.g., video upload/publish, basic profile, analytics).
• Some endpoints only for Business Accounts connected to your app.

Core Capabilities

• Initiate upload → transfer video bytes → publish post with caption/cover.
• Retrieve account/profile info and content performance (where allowed).
• Webhooks/Subscriptions available for certain events; otherwise poll.

Typical Flow

1. User connects Business account via OAuth.
2. Initialize upload → send bytes → publish with caption/cover.
3. Store returned IDs; fetch analytics later.

Gotchas

• Personal accounts have limited API posting support.
• Uploads can be large; use chunked transfer and retry logic.
• Regional restrictions & content policies may block publishing.

Auth & Setup

• Auth (API key): Authorization: Basic with base64 of anystring:API_KEY. Datacenter comes from key suffix (e.g., us9).
• Auth (OAuth): Bearer token (Authorization: Bearer <access_token>).
• Base URL: https://<dc>.api.mailchimp.com/3.0 (replace <dc> with your datacenter).
• IDs: A “list” is an audience (list_id). Contacts are addressed by subscriber_hash = MD5(lowercase(email)).

Core Capabilities

• Audiences: create/update, fields (merge fields), interest groups.
• Members: upsert (subscribe/pending/unsubscribe/archive), tags.
• Campaigns: create, set content, send; templates; folders.
• Webhooks: subscribe to audience events (subscribe, profile updates, cleaned).
• Reports & Insights: campaign and audience-level metrics.

List / Manage Merge Fields

Copy# 1) List merge fields to discover tags (e.g., FNAME, LNAME, ODOO)
GET https://<dc>.api.mailchimp.com/3.0/lists/{list_id}/merge-fields
Authorization: Basic <base64(anystring:API_KEY)>

# 2) Create a custom merge field "Odoo ID" with tag ODOO (example)
POST https://<dc>.api.mailchimp.com/3.0/lists/{list_id}/merge-fields
Authorization: Basic <base64(anystring:API_KEY)>
Content-Type: application/json

{
  "name": "Odoo ID",
  "type": "text",
  "tag": "ODOO",
  "required": false,
  "public": true
}

Create an Audience (List)

CopyPOST https://<dc>.api.mailchimp.com/3.0/lists
Authorization: Basic <base64(anystring:API_KEY)>
Content-Type: application/json

{
  "name": "Karathen Customers",
  "permission_reminder": "You are receiving this because you opted in at checkout.",
  "email_type_option": true,
  "contact": {
    "company": "Karathen",
    "address1": "500 Main St",
    "city": "Tampa",
    "state": "FL",
    "zip": "33602",
    "country": "US"
  },
  "campaign_defaults": {
    "from_name": "Karathen",
    "from_email": "no-reply@karathen.com",
    "subject": "",
    "language": "en"
  }
}

Typical Contact Flow

1. Ensure merge fields exist (e.g., ODOO custom field).
2. Compute subscriber_hash → PUT member with status_if_new.
3. Apply tags for segments; update profile fields as needed.
4. Listen to webhooks for changes (unsubscribed, cleaned, profile updates).

Common Gotchas

• Archived vs Deleted: Archived contacts can usually be re-subscribed via PUT with status/status_if_new. Permanently deleted contacts must re-opt-in via a form; API will reject.
• “Signed up to a lot of lists recently”: Anti-abuse throttle—try later or use double opt-in (pending), or have the user confirm via your hosted form.
• Field Tags: Use the merge field tag (e.g., ODOO), not the display name (“Odoo ID”). Discover via /merge-fields.
• Status transitions: Some transitions require pending + confirmation depending on account settings and compliance.