Merchant Branding#

Customize merchant branding and appearance (portal, hosted checkout, receipts).

All endpoints require Authorization: Bearer <JWT>. On the three /branding endpoints, :merchantId may be me to address the caller's own merchant (tenant admins without a merchant get the tenant-level branding). The /logo endpoints need the real merchant id.

Note: merchant users (who lack the tenant-level merchants.view key) must use their merchant id for GET requests; GET /merchants/me/branding returns 403 FORBIDDEN for them because the read check matches the path segment against their merchant id.

Get Branding Settings#

GET/api/v1/merchants/:merchantId/branding

Get Branding Settingsbash

curl https://uat.auxcore.net/api/v1/merchants/8f3c2a1e-5b7d-4e9a-9c1f-2d6e8a4b7c30/branding \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

Get Branding Settingsjson

{
  "success": true,
  "data": {
    "name": "ACME Corp",
    "tagline": "Quality since 1990",
    "logoUrl": "https://cdn.example.com/logo.png",
    "logoDarkUrl": null,
    "faviconUrl": null,
    "logoData": null,
    "hasLogo": false,
    "primaryColor": "#007bff",
    "primaryDarkColor": null,
    "primaryLightColor": null,
    "secondaryColor": null,
    "accentColor": "#28a745",
    "sidebarColor": null,
    "sidebarTextColor": null,
    "darkMode": false,
    "buttonRadius": "medium",
    "fontFamily": null,
    "headingFont": null,
    "customCss": null,
    "dynamicDescriptor": "ACME CORP",
    "receiptHeader": "Thank you for shopping with us",
    "receiptFooter": null,
    "vtConfig": null,
    "displaySaveCard": false,
    "address": "100 Main St",
    "city": "Austin",
    "state": "TX",
    "postalCode": "78701",
    "country": "US",
    "contactEmail": "contact@acme.example",
    "timezone": "Central",
    "checkoutPolicies": {}
  }
}

name is the merchant's Business Name (companyName); it is edited with PUT /api/v1/merchants/:merchantId, not here. checkoutPolicies carries the resolved policy links used by hosted checkout.

Update Branding#

PUT/api/v1/merchants/:merchantId/branding

JSON body; only the fields you send are changed.

Update Brandingbash

curl -X PUT https://uat.auxcore.net/api/v1/merchants/8f3c2a1e-5b7d-4e9a-9c1f-2d6e8a4b7c30/branding \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "logoUrl": "https://cdn.example.com/newlogo.png",
    "primaryColor": "#ff6600",
    "darkMode": true
  }'

Accepted fields: tagline, logoUrl, logoDarkUrl, faviconUrl, logoData, primaryColor, primaryDarkColor, primaryLightColor, secondaryColor, accentColor, sidebarColor, sidebarTextColor, darkMode, buttonRadius, fontFamily, headingFont, customCss, dynamicDescriptor, receiptHeader, receiptFooter. name is ignored.

Response: 200 OK with the saved branding fields (same names as above, without logoData, address and policy fields).

Upload Branding with Files#

POST/api/v1/merchants/:merchantId/branding/upload

multipart/form-data with optional file fields logo, logoDark, favicon and an optional settings field holding a JSON string of branding values (tagline, colors, buttonRadius, fontFamily, headingFont, customCss).

Upload Branding with Filesbash

curl -X POST https://uat.auxcore.net/api/v1/merchants/8f3c2a1e-5b7d-4e9a-9c1f-2d6e8a4b7c30/branding/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "logo=@logo.png" \
  -F 'settings={"primaryColor":"#ff6600"}'

Files: JPEG, PNG, SVG or WebP, max 5 MB each, one file per field.
Uploaded images are stored as data: URLs in logoUrl / logoDarkUrl / faviconUrl unless the platform is configured with external storage.

Upload Logo Files#

POST/api/v1/merchants/:merchantId/logo/upload

Same file fields and limits as above, without settings. At least one file is required (400 VALIDATION_ERROR otherwise). Unlike /branding/upload, files are written to S3 (when configured) or to the service's upload directory and saved as a URL (/uploads/...), not as a data: URL. Returns { logoUrl, logoDarkUrl, faviconUrl, uploadedFiles }.

Set Logo by URL#

POST/api/v1/merchants/:merchantId/logo

Set Logo by URLjson

{ "logoUrl": "https://cdn.example.com/logo.png" }

logoUrl is required and must be a valid URL (400 VALIDATION_ERROR otherwise).

Get Logo#

GET/api/v1/merchants/:merchantId/logo

Returns { "logoUrl": "...", "companyName": "ACME Corp" }.

Delete Logo#

DELETE/api/v1/merchants/:merchantId/logo

Intended to clear logoUrl; returns { "message": "Logo deleted successfully" }. Known issue: the current implementation does not persist the cleared value, so the logo may remain. To remove a logo, send "logoUrl": null to PUT /api/v1/merchants/:merchantId/branding.

Need help? Contact support@auxcore.net