Integration and API Spec

Integration and API Spec

Refund and Returns Processing

Zendesk serves as both the workflow trigger (new or tagged ticket) and the final resolution step (ticket update and close). The automation platform polls the Zendesk Tickets API for new tickets tagged with a return or refund label, or receives events via a Zendesk webhook. Ticket data is read at trigger and written back at resolution.

// Trigger payload (inbound webhook from Zendesk Trigger)
ticket.id          : integer
ticket.subject     : string
ticket.tags        : array<string>
ticket.custom_fields[order_reference] : string
requester.email    : string
// Write-back (PATCH /api/v2/tickets/{id})
ticket.status      : 'solved'
ticket.tags        : append ['auto-resolved','refund-processed']
ticket.comment.body: internal note with refund outcome and reason code

Shopify is used by Agent 1 to fetch order details for eligibility checking, and by Agent 2 to initiate the refund against the confirmed order. Both operations use the Shopify Admin REST API via a custom app installed on the store.

// Order fetch (GET /admin/api/2024-01/orders/{order_id}.json)
order.id                    : integer
order.created_at            : ISO8601 datetime
order.financial_status      : string
order.line_items[].id       : integer
order.line_items[].quantity : integer
order.line_items[].price    : decimal string
order.customer.email        : string
// Refund creation (POST /admin/api/2024-01/orders/{order_id}/refunds.json)
refund.refund_line_items[].line_item_id : integer
refund.refund_line_items[].quantity     : integer
refund.notify                           : true
refund.note                             : string (reason code)
// Response
refund.id          : integer  -> stored for Xero credit note reference

Xero is used by Agent 2 to create a credit note matched to the customer account and original invoice following a successful Shopify refund. The integration uses the Xero Accounting API via an OAuth 2.0 connected app registered in the Xero developer portal.

// Contact lookup (GET /Contacts?where=EmailAddress=="{email}")
Contact.ContactID  : GUID  -> stored for credit note payload
// Credit note creation (PUT /CreditNotes)
CreditNote.Type              : 'ACCRECCREDIT'
CreditNote.Contact.ContactID : GUID
CreditNote.Date              : ISO8601 date (today)
CreditNote.LineItems[].Description  : string (reason code + order reference)
CreditNote.LineItems[].Quantity     : integer
CreditNote.LineItems[].UnitAmount   : decimal
CreditNote.LineItems[].AccountCode  : XERO_ACCOUNT_CODE_REFUNDS
CreditNote.CurrencyCode             : string
CreditNote.Status                   : 'AUTHORISED'
// Response
CreditNote.CreditNoteID : GUID  -> logged to Zendesk internal note

Gmail is used by Agent 2 to send the customer-facing refund approval email. The integration uses the Gmail API via an OAuth 2.0 service account or delegated user credential tied to a shared support inbox.

// Send message (POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send)
message.raw : base64url-encoded RFC 2822 message
  To      : ticket.requester.email
  From    : GMAIL_SENDER_ADDRESS
  Subject : 'Your refund for order {{order_id}} has been approved'
  Body    : rendered GMAIL_TEMPLATE_APPROVAL_ID with field substitutions
// Response
message.id        : string  -> logged to Zendesk internal note
message.threadId  : string

Slack is used by Agent 2 to post a structured alert to the designated channel when a refund exceeds the configured high-value threshold. The integration uses an incoming webhook URL tied to a dedicated Slack app installed on the workspace.

// POST to SLACK_WEBHOOK_URL (or chat.postMessage)
{
  "channel"  : SLACK_ALERT_CHANNEL_ID,
  "blocks": [
    { "type": "header", "text": { "type": "plain_text", "text": "High-Value Refund Alert" } },
    { "type": "section", "fields": [
        { "type": "mrkdwn", "text": "*Order ID:* {{order_id}}" },
        { "type": "mrkdwn", "text": "*Amount:* ${{refund_amount}}" },
        { "type": "mrkdwn", "text": "*Customer:* {{customer_name}}" },
        { "type": "mrkdwn", "text": "*Reason:* {{reason_code}}" }
    ]}
  ]
}
// Response: HTTP 200 'ok'

// Credential store: required keys (all values injected at runtime)

// Zendesk
ZENDESK_SUBDOMAIN          : string   // e.g. 'yourcompany' (no .zendesk.com suffix)
ZENDESK_EMAIL              : string   // service account email
ZENDESK_API_TOKEN          : string   // from Admin Center > APIs
ZENDESK_WEBHOOK_SECRET     : string   // shared secret for HMAC-SHA256 validation
ZENDESK_NOTE_TEMPLATE_ID   : string   // internal note template reference

// Shopify
SHOPIFY_STORE_HANDLE       : string   // e.g. 'yourcompany' (no .myshopify.com suffix)
SHOPIFY_ADMIN_TOKEN        : string   // custom app Admin API access token

// Xero
XERO_CLIENT_ID             : string   // from Xero developer portal
XERO_CLIENT_SECRET         : string   // from Xero developer portal
XERO_REFRESH_TOKEN         : string   // rotated on each token exchange; platform persists latest
XERO_TENANT_ID             : string   // organisation GUID from GET /connections
XERO_ACCOUNT_CODE_REFUNDS  : string   // e.g. '200'; confirmed with finance manager

// Gmail
GMAIL_CLIENT_ID            : string   // Google Cloud Console OAuth 2.0 client
GMAIL_CLIENT_SECRET        : string
GMAIL_REFRESH_TOKEN        : string   // scoped to gmail.send only
GMAIL_SENDER_ADDRESS       : string   // shared support inbox address
GMAIL_TEMPLATE_APPROVAL_ID : string   // template reference in config store
GMAIL_TEMPLATE_REJECTION_ID: string

// Slack
SLACK_BOT_TOKEN            : string   // xoxb- prefixed bot token
SLACK_WEBHOOK_URL          : string   // incoming webhook URL for alert channel
SLACK_ALERT_CHANNEL_ID     : string   // channel ID (not name)
SLACK_SIGNING_SECRET       : string   // for future inbound event validation

// Workflow config (non-secret, stored in config store not credential store)
REFUND_HIGH_VALUE_THRESHOLD : number  // e.g. 150 (USD); confirmed with finance manager
RETURN_WINDOW_DAYS          : number  // e.g. 30; confirmed with business owner
EXCLUDED_PRODUCT_TAG_LIST   : array   // e.g. ['final-sale','non-returnable']