POST legal_entity_applications/[id]/pay/coupon

Apply a coupon to the legal-entity application invoice. If the application is already signed, this also submits it for review.

Endpoint

POST /api/v1/legal_entity_applications/{id}/pay/coupon

Authentication

This endpoint accepts:

• a standard API key (sk-)
• an Agent Key (ak-) with the agent:entity.application.pay scope

Send the key in the Authorization header:

Authorization: Bearer <your-api-key-or-agent-key>

Preconditions

• The application must still be in Draft.
• The application must have been created through the public API.
• The coupon must fully cover the invoice amount.
• If you are using an Agent Key, the account owner must have created that key after signing a Manifestation of Will.

Signature is not required before calling this endpoint. If the application has not been signed yet, payment still succeeds and the response includes a reminder message.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Legal-entity application ID.

Request Body

Field	Type	Required	Description
couponCode	string	Yes	Coupon code to apply to the application invoice.

Example Request

curl -X POST https://portal.eprospera.com/api/v1/legal_entity_applications/12345678-abcd-1234-abcd-123456789012/pay/coupon \
  -H "Authorization: Bearer <your-api-key-or-agent-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "couponCode": "STARTUP100"
  }'

Response

Success Response (200 OK)

Field	Type	Description
success	boolean	Always true on success.
data	object	Application row after payment processing.
message	string	Present only when the invoice is paid but the application still needs a signature.

Example Response: paid, not yet signed

{
  "success": true,
  "data": {
    "id": "12345678-abcd-1234-abcd-123456789012",
    "statusId": "Draft",
    "applicationVersion": "1.0.0",
    "submittedAt": null,
    "createdAt": "2024-01-15T09:15:00.000Z",
    "approvedAt": null,
    "rejectedAt": null
  },
  "message": "Application paid, but not signed yet - please sign the application to complete the process."
}

Example Response: signed and submitted

{
  "success": true,
  "data": {
    "id": "12345678-abcd-1234-abcd-123456789012",
    "statusId": "Pending Review",
    "applicationVersion": "1.0.0",
    "submittedAt": "2024-01-15T11:30:00.000Z",
    "createdAt": "2024-01-15T09:15:00.000Z",
    "approvedAt": null,
    "rejectedAt": null
  }
}

Behavior

This endpoint:

1. verifies the application belongs to the API-key owner
2. verifies the application is still a draft
3. ensures an invoice exists
4. applies the coupon with full-coverage enforcement
5. submits the application immediately only if the Agreement of Coexistence is already signed

Status transitions

• If the application is unsigned: it stays Draft and returns a message.
• If the application is already signed: it moves from Draft to Pending Review.

Error Responses

400 Bad Request

Application is not a draft:

{
  "error": "Legal entity application is not in draft status"
}

Application was not created through the public API:

{
  "error": "This endpoint can only be used for API-created applications"
}

Invalid coupon:

{
  "error": "Coupon code is invalid"
}

Coupon expired:

{
  "error": "Coupon code has expired"
}

Coupon already redeemed:

{
  "error": "Coupon code has already been redeemed"
}

Coupon does not fully cover the invoice:

{
  "error": "Coupon code does not cover the full invoice amount"
}

404 Not Found

{
  "error": "Legal entity application invoice not found"
}

409 Conflict

Coupon payment succeeded, but automatic submission could not complete:

{
  "error": "Coupon payment was applied, but the application could not be submitted automatically. Open the application in the portal to review its current status."
}

401 Unauthorized

{
  "error": "Missing API key"
}

or:

{
  "error": "Invalid API key"
}

403 Forbidden

Agent Key missing the required scope:

{
  "error": "Insufficient permissions"
}

404 Not Found

{
  "error": "Legal entity application not found"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Notes

• Once the application reaches Pending Review, this endpoint can no longer be used.
• Successful Agent Key calls to this endpoint are audited and notify the account owner by email.