Hide-My-Email.info API Documentation
All documents

Plans, Add-Ons, Orders, Payments, and Receipts

Catalog Endpoints

The catalog endpoints in this document are account-scoped and require secret: sk1_... and x-account-access-id: aid1...., or a logged-in browser session.

Plan list available to the account

GET /api/v1/plans/public

Returns the public plans that the authenticated account may purchase. Changes to a public plan definition apply to future reads of this catalog without requiring changes to already stored user-owned plan sessions.

Headers

  • secret: sk1_...
  • x-account-access-id: aid1....
  • Optional: Accept: application/json

Path parameters

  • None

Query parameters

  • None

Request body

  • None

Response fields

  • []
  • [].id
  • [].code
  • [].name
  • [].iconName
  • [].description
  • [].periodDays
  • [].grossAmount
  • [].vatPercent
  • [].currency
  • [].includedMessages
  • [].usersLimit
  • [].emailLimitMaxExtension
  • [].usersLimitMaxExtension
  • [].tenMinuteMailRequestsPerMonth
  • [].tenMinuteMailRequestsMaxExtension
  • [].featuresCsv
  • [].inDevelopmentFeaturesCsv
  • [].isPublic
  • [].isActive
  • [].sortOrder

Response codes

  • 200 OK
  • 401 Unauthorized

Example

curl "http://Hide-My-Email.info/api/v1/plans/public" \
  -H "secret: sk1_example" \
  -H "x-account-access-id: aid1_example"

Add-on list available to the account

GET /api/v1/add-ons

Returns the add-ons that the authenticated account may purchase for the current plan context.

Headers

  • secret: sk1_...
  • x-account-access-id: aid1....
  • Optional: Accept: application/json

Path parameters

  • None

Query parameters

  • None

Request body

  • None

Response fields

  • addOns[]
  • addOns[].addOn
  • addOns[].activeQuantity
  • addOns[].maxQuantity
  • addOns[].availableQuantity
  • addOns[].summary

The nested addOn object contains:

  • id
  • code
  • name
  • iconName
  • description
  • addOnType
  • unitAmount
  • netAmount
  • vatPercent
  • currency
  • isPublic
  • isActive
  • sortOrder

netAmount is the net add-on price. VAT is calculated separately from the selected billing country and region metadata. See Billing countries and Billing regions for a country.

addOn.addOnType values:

  • Messages - increases the e-mail message limit
  • Users - increases the linked-user limit
  • TenMinuteRequests - increases the 10-minute alias request limit

Response codes

  • 200 OK
  • 401 Unauthorized

Example

curl "http://Hide-My-Email.info/api/v1/add-ons" \
  -H "secret: sk1_example" \
  -H "x-account-access-id: aid1_example"

Add-on details available to the account

`GET /api/v1/add-ons/

Returns one add-on together with account-specific availability and quantity information.

Headers

  • secret: sk1_...
  • x-account-access-id: aid1....
  • Optional: Accept: application/json

Path parameters

  • id

Query parameters

  • None

Request body

  • None

Response fields

  • addOn
  • activeQuantity
  • maxQuantity
  • availableQuantity
  • summary

The nested addOn object contains:

  • id
  • code
  • name
  • iconName
  • description
  • addOnType
  • unitAmount
  • netAmount
  • vatPercent
  • currency
  • isPublic
  • isActive
  • sortOrder

netAmount is the net add-on price. VAT is calculated separately from the selected billing country and region metadata. See Billing countries and Billing regions for a country.

addOn.addOnType values:

  • Messages - increases the e-mail message limit
  • Users - increases the linked-user limit
  • TenMinuteRequests - increases the 10-minute alias request limit

Response codes

  • 200 OK
  • 401 Unauthorized
  • 404 Not Found

Example

curl "http://Hide-My-Email.info/api/v1/add-ons/messages-1000" \
  -H "secret: sk1_example" \
  -H "x-account-access-id: aid1_example"

Plan feature definitions available to the account

GET /api/v1/plan-features/public

Returns the feature definitions used by plans shown to the authenticated account. The returned feature list is presentation metadata for plans; it does not itself grant access to any capability.

Headers

  • secret: sk1_...
  • x-account-access-id: aid1....
  • Optional: Accept: application/json

Path parameters

  • None

Query parameters

  • None

Request body

  • None

Response fields

  • []
  • [].id
  • [].name
  • [].infoPagePath
  • [].description
  • [].sortOrder
  • [].inDevelopment

Response codes

  • 200 OK
  • 401 Unauthorized

Example

curl "http://Hide-My-Email.info/api/v1/plan-features/public" \
  -H "secret: sk1_example" \
  -H "x-account-access-id: aid1_example"

Billing Catalog Endpoints

The billing country and region catalogs are account-scoped and require secret: sk1_... and x-account-access-id: aid1.....

Billing countries

GET /api/v1/billing/countries

Returns billing countries with VAT metadata for the authenticated account flow. Use this endpoint to populate country selection before creating a plan or add-on order.

Headers

  • secret: sk1_...
  • x-account-access-id: aid1....
  • Optional: Accept: application/json

Path parameters

  • None

Query parameters

  • None

Request body

  • None

Response fields

  • countries[]
  • countries[].code
  • countries[].name
  • countries[].vatPercent
  • countries[].taxableBasePercent
  • countries[].requiresRegion
  • countries[].disableReverseCharge

Field meaning:

  • requiresRegion - the caller must choose a region before pricing can be finalized for that country
  • disableReverseCharge - reverse-charge billing must not be offered for that country
  • taxableBasePercent - optional percentage of the gross taxable base used by local tax rules; null means the full taxable base is used

Response codes

  • 200 OK
  • 401 Unauthorized

Example

curl "http://Hide-My-Email.info/api/v1/billing/countries" \
  -H "secret: sk1_example"

Billing regions for a country

`GET /api/v1/billing/countries/

Returns regions for the selected billing country. Call this endpoint only when the selected country reports requiresRegion: true.

Headers

  • secret: sk1_...

Path parameters

  • countryCode - billing country code, for example PL

Query parameters

  • None

Request body

  • None

Response fields

  • []
  • [].code
  • [].name
  • [].vatPercent
  • [].taxableBasePercent
  • [].disableReverseCharge

Field meaning:

  • disableReverseCharge - reverse-charge billing must not be offered for that region
  • taxableBasePercent - optional percentage of the gross taxable base used by local tax rules; null means the full taxable base is used

Response codes

  • 200 OK
  • 401 Unauthorized
  • 404 Not Found when the country is unknown or has no region catalog

Example

curl "http://Hide-My-Email.info/api/v1/billing/countries/PL/regions" \
  -H "secret: sk1_example"

Account Plan State

List plans visible to the account

GET /api/v1/plans

Returns the effective plan catalog visible to the authenticated account. This is the same purchase-facing plan set used by the web application for plan selection.

Headers

  • secret: sk1_...

Response fields

  • []
  • each plan object contains:
    • id
    • code
    • name
    • iconName
    • description
    • periodDays
    • grossAmount
    • vatPercent
    • currency
    • includedMessages
    • usersLimit
    • emailLimitMaxExtension
    • usersLimitMaxExtension
    • tenMinuteMailRequestsPerMonth
    • tenMinuteMailRequestsMaxExtension
    • featuresCsv
    • inDevelopmentFeaturesCsv
    • isPublic
    • isActive
    • sortOrder

Response codes

  • 200 OK
  • 401 Unauthorized

Example

curl "http://Hide-My-Email.info/api/v1/plans" -H "secret: sk1_example"

Read current active plan session state

GET /api/v1/plans/user/current

Returns the current active plan session for the account, including plan period timing and active add-on effects. Billing periods are 30-day based service periods that begin when a paid order is activated, not when the order draft is created.

Headers

  • secret: sk1_...

Response fields

  • hasActiveUserPlan
  • activePlan
  • activePlanActivatedAtUtc
  • activePlanCurrentPeriodEndsAtUtc
  • activePlanEndsAtUtc
  • extraMessages
  • extraUsers
  • extraTenMinuteRequests
  • activeAddOnDetails[]
  • activeAddOns[]
  • cachedAtUtc

activePlan contains:

  • id
  • code
  • name
  • iconName
  • description
  • periodDays
  • grossAmount
  • vatPercent
  • currency
  • includedMessages
  • usersLimit
  • emailLimitMaxExtension
  • usersLimitMaxExtension
  • tenMinuteMailRequestsPerMonth
  • tenMinuteMailRequestsMaxExtension
  • featuresCsv
  • inDevelopmentFeaturesCsv
  • isPublic
  • isActive
  • sortOrder

Response codes

  • 200 OK
  • 401 Unauthorized

Example

curl "http://Hide-My-Email.info/api/v1/plans/user/current" -H "secret: sk1_example"

Read active carry-over add-ons

GET /api/v1/add-ons/active-carry-over

Returns add-ons that can be carried into a new plan order. This is used when a replacement plan order may include existing active add-ons instead of forcing the account to purchase them again for the new plan period.

Headers

  • secret: sk1_...

Response fields

  • []
  • [].activeAddOnId
  • [].sourceOrderId
  • [].code
  • [].name
  • [].addOnType
  • [].unitAmount
  • [].quantity
  • [].monthlyNetAmount
  • [].currency

[].addOnType values:

  • Messages - increases the e-mail message limit
  • Users - increases the linked-user limit
  • TenMinuteRequests - increases the 10-minute alias request limit

monthlyNetAmount is the net monthly price of the carried add-on quantity. VAT is still resolved separately from the selected billing country and region metadata. See Billing countries and Billing regions for a country.

Response codes

  • 200 OK
  • 401 Unauthorized

Example

curl "http://Hide-My-Email.info/api/v1/add-ons/active-carry-over" -H "secret: sk1_example"

Order Endpoints

List account orders

GET /api/v1/orders

Returns order history for the authenticated account, including draft, pending, paid, active, cancelled, and failed orders.

Headers

  • secret: sk1_...

Response fields

  • []
  • each order contains:
    • id
    • orderNumber
    • itemType
    • planId
    • planName
    • addOnType
    • addOnCoverageMode
    • addOnUnitAmount
    • quantity
    • chargedDays
    • periodDays
    • netAmount
    • vatPercent
    • vatAmount
    • grossAmount
    • currency
    • buyerEmail
    • taxIdVatId
    • buyerCountryCode
    • buyerCountryName
    • buyerRegionCode
    • buyerRegionName
    • isBusinessCustomer
    • usesReverseCharge
    • buyerName
    • status
    • paymentStatus
    • latestPaymentId
    • createdAtUtc
    • paidAtUtc
    • activatedAtUtc
    • cancelledAtUtc
    • includedAddOns[]

Field meaning:

  • itemType
    • Plan - the order purchases or renews a billing plan
    • AddOn - the order purchases an add-on
  • status
    • Draft - order exists but has not yet been paid
    • AwaitingPayment - order is waiting for payment completion
    • AwaitingActivation - payment succeeded and activation is pending
    • Active - purchased service is active
    • Paid - payment succeeded for an order that does not create an active service state on its own
    • Cancelled - order was cancelled
    • Failed - order failed and cannot continue
  • paymentStatus
    • Created - payment attempt exists but checkout was not started or completed yet
    • Pending - payment provider reports that payment is still in progress
    • Succeeded - payment succeeded
    • Refunded - payment was refunded fully or partially
    • Cancelled - payment was cancelled
    • Failed - payment failed
  • addOnType
    • Messages - increases the e-mail message limit
    • Users - increases the linked-user limit
    • TenMinuteRequests - increases the 10-minute alias request limit
  • addOnCoverageMode
    • CurrentPeriod - covers only the current active 30-day period
    • EntireActivePlan - covers all remaining active periods of the current plan

Response codes

  • 200 OK
  • 401 Unauthorized

Example

curl "http://Hide-My-Email.info/api/v1/orders" -H "secret: sk1_example"

Read one order

`GET /api/v1/orders/

Returns the detailed state of one order belonging to the authenticated account.

Path parameters

  • orderId

Response fields

  • id
  • orderNumber
  • itemType
  • planId
  • planName
  • addOnType
  • addOnCoverageMode
  • addOnUnitAmount
  • quantity
  • chargedDays
  • periodDays
  • netAmount
  • vatPercent
  • vatAmount
  • grossAmount
  • currency
  • buyerEmail
  • taxIdVatId
  • buyerCountryCode
  • buyerCountryName
  • buyerRegionCode
  • buyerRegionName
  • isBusinessCustomer
  • usesReverseCharge
  • buyerName
  • status
  • paymentStatus
  • latestPaymentId
  • createdAtUtc
  • paidAtUtc
  • activatedAtUtc
  • cancelledAtUtc
  • includedAddOns[]

Field meaning:

  • itemType
    • Plan - the order purchases or renews a billing plan
    • AddOn - the order purchases an add-on
  • status
    • Draft - order exists but has not yet been paid
    • AwaitingPayment - order is waiting for payment completion
    • AwaitingActivation - payment succeeded and activation is pending
    • Active - purchased service is active
    • Paid - payment succeeded for an order that does not create an active service state on its own
    • Cancelled - order was cancelled
    • Failed - order failed and cannot continue
  • paymentStatus
    • Created - payment attempt exists but checkout was not started or completed yet
    • Pending - payment provider reports that payment is still in progress
    • Succeeded - payment succeeded
    • Refunded - payment was refunded fully or partially
    • Cancelled - payment was cancelled
    • Failed - payment failed
  • addOnType
    • Messages - increases the e-mail message limit
    • Users - increases the linked-user limit
    • TenMinuteRequests - increases the 10-minute alias request limit
  • addOnCoverageMode
    • CurrentPeriod - covers only the current active 30-day period
    • EntireActivePlan - covers all remaining active periods of the current plan

Response codes

  • 200 OK
  • 401 Unauthorized
  • 404 Not Found

Example

curl "http://Hide-My-Email.info/api/v1/orders/order_123" -H "secret: sk1_example"

Create a plan order

POST /api/v1/orders

Creates a new plan order draft for the authenticated account. If another paid plan is still active, activation of the new order may be queued until the earlier paid plan reaches the end of its active period.

Request body fields

  • planId - required
  • periodDays - optional, defaults to 30
  • buyerEmail - optional
  • taxIdVatId - optional
  • saveTaxIdVatIdInAccount - optional boolean
  • buyerCountryCode - optional
  • buyerRegionCode - optional
  • isBusinessCustomer - optional boolean
  • useReverseCharge - optional boolean
  • buyerName - optional
  • includedActiveAddOnIds[] - optional

Response fields

  • success
  • message
  • order

order contains the same fields documented for GET /api/v1/orders/{orderId} above.

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized

Example

curl -X POST "http://Hide-My-Email.info/api/v1/orders" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"planId\":\"plan-pro\",\"periodDays\":30,\"buyerEmail\":\"billing@example.com\",\"taxIdVatId\":\"PL1234567890\",\"saveTaxIdVatIdInAccount\":true,\"buyerCountryCode\":\"PL\",\"buyerRegionCode\":null,\"isBusinessCustomer\":true,\"useReverseCharge\":false,\"buyerName\":\"Example Company\",\"includedActiveAddOnIds\":[]}"

Create an add-on order

POST /api/v1/orders/add-on

Creates a new add-on order draft for the authenticated account. Depending on coverageMode, the add-on can affect only the current 30-day period or every remaining period of the currently active plan.

Request body fields

  • addOnId - required
  • quantity - optional, default 1
  • coverageMode - optional, CurrentPeriod or EntireActivePlan
  • buyerEmail
  • taxIdVatId
  • saveTaxIdVatIdInAccount
  • buyerCountryCode
  • buyerRegionCode
  • isBusinessCustomer
  • useReverseCharge
  • buyerName

coverageMode values:

  • CurrentPeriod - covers only the current active 30-day period
  • EntireActivePlan - covers all remaining active periods of the current plan

The add-on order price fields returned by this endpoint are net amounts. VAT is calculated separately from the selected billing country and region metadata. See Billing countries and Billing regions for a country.

Response fields

  • success
  • message
  • order

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized

Example

curl -X POST "http://Hide-My-Email.info/api/v1/orders/add-on" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"addOnId\":\"messages-1000\",\"quantity\":1,\"coverageMode\":\"CurrentPeriod\",\"buyerEmail\":\"billing@example.com\",\"taxIdVatId\":\"PL1234567890\",\"saveTaxIdVatIdInAccount\":true,\"buyerCountryCode\":\"PL\",\"buyerRegionCode\":null,\"isBusinessCustomer\":true,\"useReverseCharge\":false,\"buyerName\":\"Example Company\"}"

Read cancellation preview

`GET /api/v1/orders/

Returns the cancellation and refund calculation that would apply if the order were cancelled now. Refunds depend on actual usage and may be reduced or unavailable when service capacity has already been consumed.

Path parameters

  • orderId

Response fields

  • canCancel
  • message
  • cancelsPendingPayment
  • refundEligible
  • remainsActiveUntilPeriodEnd
  • activeUntilUtc
  • paidAmount
  • currency
  • buyerCountryName
  • buyerRegionName
  • taxIdVatId
  • isBusinessCustomer
  • usesReverseCharge
  • buyerName
  • itemType
  • addOnType
  • addOnUnitAmount
  • quantity
  • vatPercent
  • refundUsageLabel
  • includedUsageUnits
  • usedUsageUnits
  • includedMessages
  • usedMessages
  • allowedTenMinuteRequests
  • usedTenMinuteRequests
  • usagePercent
  • refundPercent
  • usageBasedRefundAmount
  • tenMinuteDeductionAmount
  • refundAmount
  • planFeatures[]
  • inDevelopmentFeatures[]
  • activeAddOns[]

Response codes

  • 200 OK
  • 401 Unauthorized
  • 404 Not Found

Example

curl "http://Hide-My-Email.info/api/v1/orders/order_123/cancellation-preview" -H "secret: sk1_example"

Cancel an order

`POST /api/v1/orders/

Cancels an eligible order. For unpaid orders this typically stops the checkout flow; for paid orders the service applies the same refund and deactivation rules shown by the cancellation preview.

Path parameters

  • orderId

Request body

  • None

Response fields

  • success
  • message
  • order

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found

Example

curl -X POST "http://Hide-My-Email.info/api/v1/orders/order_123/cancel" -H "secret: sk1_example"

Download receipt PDF

`GET /api/v1/orders/

Returns a PDF file for the resolved account only. The returned document is the current payment confirmation / receipt for that order and is the same type of document the account owner can download in the web UI.

Path parameters

  • orderId

Headers

  • secret: sk1_...
  • Optional: Accept: application/pdf

Response

  • PDF file stream

Response codes

  • 200 OK
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found

Example

curl -L "http://Hide-My-Email.info/api/v1/orders/order_123/receipt-pdf" \
  -H "secret: sk1_example" \
  -o receipt.pdf

Payment Endpoints

List payments

GET /api/v1/payments

Returns payment attempts associated with the authenticated account, optionally filtered to a single order.

Query parameters

  • orderId - optional, filters to one order

Response fields

  • []
  • [].id
  • [].orderId
  • [].provider
  • [].status
  • [].externalPaymentId
  • [].checkoutUrl
  • [].createdAtUtc
  • [].updatedAtUtc

[].status values:

  • Created - payment attempt exists but checkout was not started or completed yet
  • Pending - payment provider reports that payment is still in progress
  • Succeeded - payment succeeded
  • Refunded - payment was refunded fully or partially
  • Cancelled - payment was cancelled
  • Failed - payment failed

Response codes

  • 200 OK
  • 401 Unauthorized

Example

curl "http://Hide-My-Email.info/api/v1/payments?orderId=order_123" -H "secret: sk1_example"

Start payment checkout

POST /api/v1/payments/start

Creates or resumes a checkout session for an existing order. The checkout URL returned by this endpoint is the URL that the client should open for payment.

Request body fields

  • orderId - required
  • enableAutomaticPayments - optional boolean
  • buyerEmail - optional
  • buyerFirstName - optional
  • buyerLastName - optional
  • buyerPhone - optional
  • buyerExternalId - optional
  • buyerDeviceFingerprint - optional
  • existingPaymentId - optional
  • continueUrl - optional

Response fields

  • success
  • message
  • payment
  • payment.id
  • payment.orderId
  • payment.provider
  • payment.status
  • payment.externalPaymentId
  • payment.checkoutUrl
  • payment.createdAtUtc
  • payment.updatedAtUtc

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized

Example

curl -X POST "http://Hide-My-Email.info/api/v1/payments/start" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"orderId\":\"order_123\",\"enableAutomaticPayments\":false,\"buyerEmail\":\"billing@example.com\",\"buyerFirstName\":\"Alice\",\"buyerLastName\":\"Example\",\"buyerPhone\":\"+48123123123\",\"buyerExternalId\":\"crm-123\",\"buyerDeviceFingerprint\":\"fingerprint\",\"existingPaymentId\":null,\"continueUrl\":\"http://Hide-My-Email.info/my-account/orders\"}"
© 2026 PrivacyGuard.company. All rights reserved.