patch payment method.md

Patch Payment Method

Management API · Payment

PATCH https://app.mk.io/api/v1/organization/paymentMethods/{paymentmethod_id}

Partially update a payment method using JSON Patch (RFC 6902). Requires Content-Type: application/json-patch+json.

The following field can be updated via replace operations:

/metadata/displayName — a human-friendly display name (max 256 characters, or "" to clear).

RBAC Capability Required: core.subscription.update

Authentication

Authorization header — Bearer authentication of the form Bearer <token>.

Path parameters

Name	Type	Required	Description
`paymentmethod_id`	string	Yes	format: uuid

Request body

Content type: application/json-patch+json

Array items (object):
- op · enum · Required — Operation
  - Allowed values: add, remove, replace, stringReplace, numberReplace
- path · string · Required — Path
- search · string · Optional — Search string for 'stringReplace' and 'numberReplace' operations. 'numberReplace' replaces with JSON number type but only when the search string matches the entire value. I.e "audio_pid" would be replaced with 50, not "50".
- value · any · Optional — Value

Example request

curl -X PATCH "https://app.mk.io/api/v1/organization/paymentMethods/{paymentmethod_id}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
  {
    "op": "replace",
    "path": "/metadata/displayName",
    "value": ""
  }
]'

Responses

200 — The updated payment method.

metadata · object · Optional — Metadata.
- created · string · Optional · format: date-time — The time when the resource was created
- createdBy · string · Optional · format: uuid — ID of the user who created the resource
- createdByEmail · string · Optional — Email of the user who created the resource
- displayName · string · Optional — The display name of the resource
- id · string · Required · format: uuid — The ID of the resource
- organizationId · string or null · Required · format: uuid — The ID of the organization this Payment Method belongs to.
related · object · Optional — Related data.
- projects · list of strings · Required — List of project names which are billed using this payment method.
  - Array items (string):
spec · object · Required — Specification.
- One of the following variants, selected by type:
  - azure (object)
    - allowedOrganizations · list of strings or null · Optional — If set, only these organization IDs are allowed to use this payment method.
      - Array items (string):
    - autoPurchaseBeamLicenses · boolean · Required — Specifies whether Beam usage should be billed through monthly charges (true) or by the minute (false).
    - azureOfferId · string or null · Optional — The Azure offer ID.
    - azurePlanName · string or null · Optional — The Azure plan name.
    - azurePrivateOfferId · string · Optional · format: uuid — The Partner Center private offer UUID. Present only for azure_private_offer payment methods.
    - azureSaasSubscriptionAutoRenew · boolean or null · Optional
    - azureSaasSubscriptionEnd · string or null · Optional
    - azureSaasSubscriptionId · string or null · Optional
    - azureSaasSubscriptionName · string or null · Optional
    - azureSaasSubscriptionStart · string or null · Optional
    - azureSaasSubscriptionStatus · string or null · Optional
    - endDate · string or null · Required · format: date — The date this payment method expires, in yyyy-mm-dd format. It is not valid on this day. If not set, this payment method never expires. If startDate is also set, endDate must be after startDate.
    - notes · string · Optional · <=256 characters — Note to the customer.
    - productPublicationName · string · Required — The name of the product publication that details the pricing for this payment method.
    - startDate · string or null · Required · format: date — The date this payment method becomes eligible to be active, in yyyy-mm-dd format. It is valid on this day. If not set, there is no lower bound. If both startDate and endDate are set, endDate must be after startDate.
    - type · string · Required — Payment method type. Defaults to direct if not specified.
  - aws (object)
    - allowedOrganizations · list of strings or null · Optional — If set, only these organization IDs are allowed to use this payment method.
      - Array items (string):
    - autoPurchaseBeamLicenses · boolean · Required — Specifies whether Beam usage should be billed through monthly charges (true) or by the minute (false).
    - awsAccountId · string · Optional — The AWS account ID.
    - awsCustomerId · string or null · Optional — Unique AWS account identifier specific to AWS SaaS Marketplace.
    - awsOfferId · string · Optional — Unique AWS private offer identifier.
    - awsProductCode · string · Optional — The MK.IO product code in the AWS SaaS Marketplace.
    - awsStatus · string or null · Optional
    - endDate · string or null · Required · format: date — The date this payment method expires, in yyyy-mm-dd format. It is not valid on this day. If not set, this payment method never expires. If startDate is also set, endDate must be after startDate.
    - notes · string · Optional · <=256 characters — Note to the customer.
    - productPublicationName · string · Required — The name of the product publication that details the pricing for this payment method.
    - startDate · string or null · Required · format: date — The date this payment method becomes eligible to be active, in yyyy-mm-dd format. It is valid on this day. If not set, there is no lower bound. If both startDate and endDate are set, endDate must be after startDate.
    - type · string · Required — Payment method type. Defaults to direct if not specified.
  - direct (object)
    - allowedOrganizations · list of strings or null · Optional — If set, only these organization IDs are allowed to use this payment method.
      - Array items (string):
    - autoPurchaseBeamLicenses · boolean · Required — Specifies whether Beam usage should be billed through monthly charges (true) or by the minute (false).
    - endDate · string or null · Required · format: date — The date this payment method expires, in yyyy-mm-dd format. It is not valid on this day. If not set, this payment method never expires. If startDate is also set, endDate must be after startDate.
    - notes · string · Optional · <=256 characters — Note to the customer.
    - productPublicationName · string · Required — The name of the product publication that details the pricing for this payment method.
    - redeemedBy · string or null · Optional — The email of the user who redeemed this sales order.
    - salesOrderNumber · string · Optional — The document number from NetSuite, SOxxx
    - startDate · string or null · Required · format: date — The date this payment method becomes eligible to be active, in yyyy-mm-dd format. It is valid on this day. If not set, there is no lower bound. If both startDate and endDate are set, endDate must be after startDate.
    - status · string · Optional — The status of the purchase order in MediaKind's systems.
    - type · string · Required — Payment method type. Defaults to direct if not specified.
status · object · Optional — Status.
- isActive · boolean · Required — Is payment method active
- termsAndConditionsAccepted · boolean · Required — Whether the Terms & Conditions of this payment method have been accepted.

Example:

{
  "metadata": {
    "created": "2024-01-01T00:00:00Z",
    "createdBy": "00000000-0000-0000-0000-000000000000",
    "createdByEmail": "string",
    "displayName": "string",
    "id": "00000000-0000-0000-0000-000000000000",
    "organizationId": "00000000-0000-0000-0000-000000000000"
  },
  "related": {
    "projects": [
      "string"
    ]
  },
  "spec": {
    "type": "azure",
    "allowedOrganizations": [
      "00000000-0000-0000-0000-000000000000"
    ],
    "autoPurchaseBeamLicenses": true,
    "azureOfferId": "string",
    "azurePlanName": "string",
    "azurePrivateOfferId": "00000000-0000-0000-0000-000000000000",
    "azureSaasSubscriptionAutoRenew": true,
    "azureSaasSubscriptionEnd": "string",
    "azureSaasSubscriptionId": "string",
    "azureSaasSubscriptionName": "string",
    "azureSaasSubscriptionStart": "string",
    "azureSaasSubscriptionStatus": "string",
    "endDate": "2099-01-01",
    "notes": "string",
    "productPublicationName": "string",
    "startDate": "2026-01-01"
  },
  "status": {
    "isActive": true,
    "termsAndConditionsAccepted": true
  }
}

400 — Bad Request

error · object · Required — Pertinent information about the error
- code · string · Required — The error code.
- detail · string · Required — The error message.
- extraDetail · map from strings to any · Optional — Extra information regarding this error.
  - [any key] · any — map of additional properties
ref · string · Required — A reference to the request that caused the error.
status · integer · Required — The HTTP status code

Example:

{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}

401 — Unauthorized

Example:

{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}

403 — Forbidden

Example:

{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}

404 — Not Found

Example:

{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}

429 — Too Many Requests

Example:

{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}

500 — Internal Server Error

Example:

{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}