Skip to main content

Create a Delivery Attempt

Overview​

Queue a request to deliver an existing Receipt via Email, SMS, or Print. Use this endpoint to resend receipts that failed delivery, send to additional recipients, or deliver via a new channel.

Resource Access​

  • User Permissions: Admin users only
  • Endpoint: POST /receipts/\{receipt_id}/delivery_attempts

Arguments​

ParameterTypeRequiredDescription
receipt_idstringYes (path)The unique ID of the Receipt to deliver
requested_delivery_methodsarrayYesArray of delivery method objects
requested_delivery_methods[].typestringYesDelivery method type: EMAIL, SMS, or PRINT
requested_delivery_methods[].destinationsarrayYesArray of email addresses, phone numbers, or Device IDs

Example Request (Resend via Email)​

curl -X POST \
  'https://api.ahrvo.network/payments/na/receipts/RCreceiptExample123/delivery_attempts' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "requested_delivery_methods": [
      {
        "type": "EMAIL",
        "destinations": ["customer@example.com"]
      }
    ]
  }'

Example Request (Send to Multiple Recipients and Channels)​

curl -X POST \
  'https://api.ahrvo.network/payments/na/receipts/RCreceiptExample123/delivery_attempts' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "requested_delivery_methods": [
      {
        "type": "EMAIL",
        "destinations": [
          "customer@example.com",
          "customer-alt@example.com"
        ]
      },
      {
        "type": "SMS",
        "destinations": [
          "+15555551234",
          "+15555555678"
        ]
      },
      {
        "type": "PRINT",
        "destinations": ["DEVICE-POS-001"]
      }
    ]
  }'

Example Response​

{
  "message": "Delivery request accepted for processing",
  "receipt_id": "RCreceiptExample123",
  "requested_delivery_methods": [
    {
      "type": "EMAIL",
      "destinations": ["customer@example.com"]
    }
  ],
  "status": "QUEUED"
}

Additional Information​

  • HTTP Status: Returns 202 Accepted to indicate the request was queued
    • Delivery is asynchronous (happens in background)
    • Response doesn't indicate success/failure of actual delivery
    • Use GET /receipts/{receipt_id}/delivery_attempts to check delivery status
  • Delivery Methods:
    • EMAIL: Send receipt to email address(es)
      • Destinations: Valid email addresses
      • Receipt sent as formatted HTML email with embedded details
      • Includes link to hosted receipt URL for full view
      • Typical delivery time: Seconds to minutes
      • Common failures: Invalid email, spam filters, mailbox full
    • SMS: Send receipt link via text message
      • Destinations: Phone numbers in E.164 format (e.g., +15555551234)
      • Must include country code (+1 for US/Canada)
      • SMS contains shortened URL to view receipt
      • Typical delivery time: Seconds to minutes
      • Character limit: ~160 characters (URL + brief message)
      • Common failures: Invalid number, carrier blocking, opt-out status
    • PRINT: Queue for printing on physical printer
      • Destinations: Device IDs of registered point-of-sale printers
      • Requires compatible hardware (thermal printers, receipt printers)
      • Device must be online and connected
      • Typical delivery time: Immediate if device is ready
      • Common failures: Device offline, out of paper, hardware error
  • Multiple Recipients: Can send to multiple destinations in one request
    • Each destination in the array gets a separate delivery attempt
    • Useful for:
      • Sending to both customer and alternate email
      • SMS to multiple phone numbers
      • Printing to backup printer if primary fails
  • Multiple Channels: Can deliver via multiple methods simultaneously
    • Example: Email and SMS in same request
    • Each method creates separate delivery attempt(s)
    • Increases likelihood customer receives receipt
  • Use Cases:
    • Resend Failed Receipts: If original delivery failed, retry with this endpoint
    • Additional Recipients: Customer requests receipt sent to different email
    • Multi-Channel Delivery: Send both email and SMS for better reach
    • Backup Delivery: Original email bounced, try SMS instead
    • Print on Demand: Customer requests printed receipt at later time
    • Customer Service: Support team resends receipt during inquiry
    • Lost Receipts: Customer lost original, send replacement
  • Idempotency: Each request creates new delivery attempt(s)
    • Not idempotent - multiple calls create multiple deliveries
    • Safe to retry if uncertain about delivery
    • Check existing delivery attempts first to avoid duplicates
  • Delivery Tracking: After creating delivery attempt:
    1. Request returns 202 Accepted immediately
    2. Delivery queued for processing
    3. Check status with GET /receipts/{receipt_id}/delivery_attempts
    4. Each attempt has status: PENDING, SUCCEEDED, or FAILED
  • Retry Logic:
    • System may automatically retry failed deliveries
    • Typically 3 retry attempts over several hours
    • Manual retry via this endpoint always creates new attempt
    • Check delivery_attempts list to avoid duplicate sends
  • Rate Limiting:
    • Consider rate limits when sending to many recipients
    • Batch large recipient lists appropriately
    • Avoid rapid repeated sends to same destination
  • Email Delivery Best Practices:
    • Use verified email addresses when possible
    • Ensure sender domain has proper SPF/DKIM/DMARC records
    • Avoid spam trigger words in receipt content
    • Provide unsubscribe option if required by jurisdiction
  • SMS Delivery Best Practices:
    • Always use E.164 format with country code
    • Verify phone numbers before sending
    • Respect opt-out preferences
    • Be aware of SMS costs (typically $0.01-$0.03 per message)
    • Consider time zones to avoid late-night deliveries
    • Include sender identification in message
  • Print Delivery Best Practices:
    • Verify printer is online before queuing
    • Monitor printer status (paper, ink/toner levels)
    • Have backup device IDs configured
    • Test print functionality regularly
    • Format receipt appropriately for thermal printers (typically 80mm width)
  • Error Handling:
    • Invalid receipt_id: 404 Not Found
    • Invalid email format: 400 Bad Request
    • Invalid phone number format: 400 Bad Request
    • Unknown device ID: Queued but will eventually fail
    • Delivery failures visible in delivery_attempts list
  • Notification: Some platforms support webhooks for delivery status
    • Get notified when delivery succeeds or fails
    • Configure webhook URL in platform settings
    • Useful for automated retry logic or customer notifications
  • Cost Considerations:
    • Email delivery: Typically no additional cost
    • SMS delivery: Per-message fees apply ($0.01-$0.03 typically)
    • Print delivery: Hardware/consumables cost only
    • Factor delivery costs into pricing model
  • Compliance:
    • Email: CAN-SPAM Act compliance (US), GDPR (EU)
    • SMS: TCPA compliance (US), requires consent
    • Maintain delivery logs for audit purposes
    • Honor opt-out requests promptly
  • Security:
    • Receipt URLs are unguessable but not password-protected
    • Don't include sensitive data in SMS/email body
    • Use receipt URL for full details
    • Consider data privacy regulations (GDPR, CCPA)