Vela Mobile API Documentation

MW API DOC

Plans

Previous Next

Manage subscriber rate plans, including plan changes, add-on purchases, and cancellations.

Change Plan

Change the rate plan for an existing subscriber.

Endpoint: POST /sim/plan/change/

Rate Limit: 30 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
new_plan_id string Yes New Plan ID (must be in user's authorized plans)
sim string No ICCID — recommended for verification
address1 string Conditional Street address (required for WFC plans)
city string Conditional City (required for WFC plans)
state string Conditional 2-letter US State Code (required for WFC plans)
zip_code string Conditional 5-digit ZIP Code (required for WFC plans)
address2 string No Street address line 2
transaction_id string No Unique Transaction ID (auto-generated with PLAN_CHANGE_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "new_plan_id": "2059",
  "sim": "89014103211118500000",
  "address1": "123 Main St",
  "city": "Dallas",
  "state": "TX",
  "zip_code": "75001",
  "transaction_id": "PLAN_CHANGE_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "PLAN_CHANGE_2092C21CF721",
  "message": "SUCCESS"
}

Success with WFC Warning (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "PLAN_CHANGE_2092C21CF721",
  "message": "SUCCESS",
  "warning": "Plan Change Completed Successfully: Failed To Add WFC due to Invalid E911 Address. Please Retry With AddWFC API",
  "wfc_status": false
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "PLAN_CHANGE_96D4A85DC0AC",
  "message": "Plan Code Already Active with MDN. (916)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "PLAN_CHANGE_D7ADC52579CA",
  "message": "Plan Code is Invalid or Inactive. (906)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "PLAN_CHANGE_47F0EB723D97",
  "message": "ESN/MDN is Inactive (915)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "PLAN_CHANGE_00627C3E7BC3",
  "message": "SUBSCRIBER WITH GIVEN RESOURCE NOT EXISTS. (918)"
}

Authorization Error (403 Forbidden):

{
  "status": "failure",
  "message": "Plan ID '2059' is not authorized for user XXX.",
  "code": "HTTP_403"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Validation Error (422 Unprocessable Entity):

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "state"],
      "msg": "Value error, State must be a 2-letter US state code (e.g., TX, CA, NY)"
    }
  ]
}

Possible Error Codes

(916), (906), (915), (918), (909), GENS-0090, GENS-0184

For full error details see Error & Response Codes.

Purchase Plan

Purchase a top-up or add-on for a subscriber.

Endpoint: POST /sim/plan/purchase/

Rate Limit: 30 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
plan_id string Yes Plan ID to purchase (must be in user's authorized plans)
address1 string No E911 Street Address (for WFC plans)
city string No E911 City
state string No E911 State — 2-letter code
zip_code string No E911 ZIP Code — 5 digits
address2 string No E911 Street Address Line 2
transaction_id string No Unique Transaction ID (auto-generated with PURCHASE_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "plan_id": "2063",
  "address1": "123 Main St",
  "city": "Dallas",
  "state": "TX",
  "zip_code": "75001",
  "transaction_id": "PURCHASE_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "PURCHASE_95FF9BD89720",
  "purchase_id": "1125899982286069",
  "message": "Success"
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "PURCHASE_96D4A85DC0AC",
  "message": "Plan Code is Invalid or Inactive. (906)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "PURCHASE_47F0EB723D97",
  "message": "ESN/MDN is Inactive (915)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "PURCHASE_00627C3E7BC3",
  "message": "SUBSCRIBER WITH GIVEN RESOURCE NOT EXISTS. (918)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "PURCHASE_B15C731E74B2",
  "message": "Max Purchases limit exceeded (969)"
}

Authorization Error (403 Forbidden):

{
  "status": "failure",
  "message": "Plan ID '2063' is not authorized for user XXX.",
  "code": "HTTP_403"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(906), (915), (918), (909), (969), GENS-0184

For full error details see Error & Response Codes.

Cancel Purchase

Cancel a previously purchased plan or add-on.

Endpoint: POST /sim/plan/cancel/

Rate Limit: 30 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
purchase_id string Yes Purchase ID to cancel (from the purchase response)
transaction_id string No Unique Transaction ID (auto-generated with CANCEL_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "purchase_id": "1125899982286069",
  "transaction_id": "CANCEL_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "CANCEL_741B5556E20A",
  "purchase_id": "1125899982286069",
  "message": "Success"
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "CANCEL_AB66155F9D51",
  "message": "NO ACTIVE SUBSCRIPTION FOUND. (949)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "CANCEL_00627C3E7BC3",
  "message": "SUBSCRIBER WITH GIVEN RESOURCE NOT EXISTS. (918)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "CANCEL_B15C731E74B2",
  "message": "ESN/MDN is Inactive (915)"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(949), (918), (915), (909), (919)

For full error details see Error & Response Codes.

Change Billing Code

Change the wholesale billing code on a subscriber's account. This changes the carrier-level cost plan assignment without affecting the subscriber-facing service plan.

Superuser Only

The billing code change endpoint requires superuser privileges. Non-superuser requests will receive HTTP 403 Forbidden.

Endpoint: POST /sim/billing-code/change/

Rate Limit: 20 requests/minute

Authentication: Bearer token required (superuser)

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
billing_code string Yes New wholesale billing code to assign
transaction_id string No Unique Transaction ID (auto-generated with CHG_BILL_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "billing_code": "BC456",
  "transaction_id": "CHG_BILL_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "CHG_BILL_1C68F4E4797B",
  "message": "Success"
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "CHG_BILL_00627C3E7BC3",
  "message": "SUBSCRIBER WITH GIVEN RESOURCE NOT EXISTS. (918)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "CHG_BILL_B15C731E74B2",
  "message": "ESN/MDN is Inactive (915)"
}

Authorization Error (403 Forbidden):

{
  "detail": "The user doesn't have enough privileges"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(918), (915), (909)

For full error details see Error & Response Codes.

Common HTTP Errors (All Endpoints on This Page)

HTTP Code Meaning
400 Bad request / upstream carrier operation failed
401 Not authenticated (missing or invalid Bearer token)
403 Forbidden (insufficient permissions or unauthorized plan)
409 Conflict (duplicate transaction_id)
422 Validation error (invalid state code, ZIP format, MDN format)
429 Rate limit exceeded
500 Internal server error

Full error reference: Error & Response Codes

Port-In Lifecycle