List Delivery Attempts for a Receipt

Overview

Retrieve a list of all delivery attempts made for a specific Receipt. Use this endpoint to check delivery status, identify failed deliveries, and audit receipt delivery history.

Resource Access

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

Arguments

Parameter	Type	Required	Description
receipt_id	string	Yes (path)	The unique ID of the Receipt
limit	integer	No	Maximum number of records to return (default: 10)

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/receipts/RCreceiptExample123/delivery_attempts?limit=20' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response

{
  "_embedded": {
    "delivery_attempts": [
      {
        "id": "DAdeliveryAttempt001",
        "created_at": "2023-12-10T14:30:15Z",
        "updated_at": "2023-12-10T14:30:22Z",
        "receipt_id": "RCreceiptExample123",
        "type": "EMAIL",
        "destination": "customer@example.com",
        "state": "SUCCEEDED"
      },
      {
        "id": "DAdeliveryAttempt002",
        "created_at": "2023-12-10T14:30:15Z",
        "updated_at": "2023-12-10T14:30:25Z",
        "receipt_id": "RCreceiptExample123",
        "type": "SMS",
        "destination": "+15555551234",
        "state": "SUCCEEDED"
      },
      {
        "id": "DAdeliveryAttempt003",
        "created_at": "2023-12-10T15:45:10Z",
        "updated_at": "2023-12-10T15:45:18Z",
        "receipt_id": "RCreceiptExample123",
        "type": "EMAIL",
        "destination": "invalid-email@",
        "state": "FAILED"
      },
      {
        "id": "DAdeliveryAttempt004",
        "created_at": "2023-12-10T16:20:00Z",
        "updated_at": "2023-12-10T16:20:00Z",
        "receipt_id": "RCreceiptExample123",
        "type": "PRINT",
        "destination": "DEVICE-POS-001",
        "state": "PENDING"
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 4
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/receipts/RCreceiptExample123/delivery_attempts?limit=20"
    },
    "receipt": {
      "href": "https://api.ahrvo.network/payments/na/receipts/RCreceiptExample123"
    }
  }
}

Additional Information

Delivery Attempt States:
- PENDING: Delivery queued but not yet attempted
  - Initial state when delivery is created
  - Typically transitions to SUCCEEDED or FAILED within seconds to minutes
  - May remain pending if system is processing backlog
  - For PRINT: Device may be offline or busy
- SUCCEEDED: Delivery completed successfully
  - Email: Sent to mail server (doesn't guarantee inbox delivery)
  - SMS: Delivered to carrier (doesn't guarantee phone receipt)
  - PRINT: Sent to printer device successfully
  - Final state - delivery is complete
- FAILED: Delivery attempt failed
  - See failure reasons below
  - Can be retried with POST /delivery_attempts
  - Final state unless manually retried
Common Failure Reasons:
- Email Failures:
  - Invalid email address format
  - Recipient's mailbox full
  - Email server rejected (spam filter, blocked sender)
  - Recipient domain doesn't exist
  - Temporary server errors (may succeed on retry)
- SMS Failures:
  - Invalid phone number format
  - Number not in service
  - Carrier rejected message
  - Recipient opted out of SMS
  - Country/carrier not supported
  - Temporary carrier issues
- Print Failures:
  - Device offline or disconnected
  - Device ID not found
  - Printer out of paper
  - Hardware error or jam
  - Network connectivity issues
Delivery Timing:
- Most deliveries complete within seconds to minutes
- created_at: When delivery was queued
- updated_at: When state last changed
- Time difference shows processing duration
- Long PENDING times may indicate issues
Multiple Attempts per Receipt: Common scenarios:
- Initial delivery at receipt creation
- Resends due to failed deliveries
- Additional recipients added later
- Multiple channels (email + SMS)
- Customer service resends
Use Cases:
- Verify Delivery: Check if receipt was successfully sent
- Troubleshoot Issues: Identify why delivery failed
- Customer Service: Confirm receipt delivery during support calls
- Audit Trail: Review delivery history for compliance
- Retry Logic: Identify failed attempts that need retry
- Analytics: Track delivery success rates by channel
- Monitoring: Alert on high failure rates
Filtering and Pagination:
- Use limit to control page size
- Default limit is 10, increase for more results
- Results typically ordered by created_at descending (newest first)
- Use pagination for receipts with many delivery attempts
Delivery Guarantees:
- Email: "Sent" doesn't guarantee inbox delivery
  - May be caught by spam filters
  - May go to junk/promotions folder
  - Recipient may have auto-delete rules
  - SUCCEEDED means accepted by recipient's mail server
- SMS: "Delivered" doesn't guarantee phone receipt
  - Phone may be off or out of coverage
  - Message may be filtered by carrier
  - SUCCEEDED means accepted by carrier
- Print: SUCCEEDED means sent to device
  - Device may still have printing issues
  - Physical receipt may not print correctly
Best Practices:
- Check delivery status before resending
- Wait reasonable time for PENDING to resolve (5-10 minutes)
- Don't retry SUCCEEDED deliveries
- Investigate FAILED deliveries before retry
- For critical receipts, use multiple channels (email + SMS)
- Monitor delivery success rates over time
- Set up alerts for high failure rates
Automated Retry: Some platforms automatically retry failed deliveries
- Typically 2-3 retry attempts
- Exponential backoff between retries
- Check delivery_attempts list to see retry history
- Manual retry always creates new attempt
Delivery Metrics: Use this data for analytics:
- Success rate by delivery type
- Average delivery time
- Common failure reasons
- Peak delivery times
- Channel preferences (email vs SMS)
Data Retention: Delivery attempts typically retained:
- Same retention period as receipts (7+ years)
- Useful for dispute resolution
- Proves delivery for compliance
- Audit trail for customer service
Webhooks: Some platforms support delivery status webhooks
- Real-time notifications when state changes
- Avoid polling this endpoint frequently
- Configure webhook URL in platform settings
- Typical events: delivery.succeeded, delivery.failed
Rate Limiting: When checking delivery status:
- Don't poll excessively (respect rate limits)
- For most use cases, check once after reasonable delay
- Use webhooks for real-time status updates
- Cache results when appropriate
Privacy Considerations:
- Delivery attempts show destination addresses
- Protect this data according to privacy regulations
- Email/phone are PII under GDPR/CCPA
- Limit access to authorized personnel
Troubleshooting Workflow:
1. Customer reports not receiving receipt
2. Call this endpoint to list delivery attempts
3. Check state of attempts:
  - PENDING: Still processing, wait longer
  - SUCCEEDED: Receipt was delivered, check spam/junk folders
  - FAILED: Review failure reason, verify destination address
4. If FAILED, correct issue and retry with POST delivery_attempts
5. Consider alternative delivery method (try SMS if email failed)
Integration Patterns:
- Polling: Check status after creating receipt/delivery
- Webhooks: Real-time status updates
- Dashboard: Display delivery status in admin UI
- Alerts: Notify support team of failures
- Reports: Aggregate delivery metrics for analysis

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​

Overview

Resource Access

Arguments

Example Request

Example Response

Additional Information